브랜치

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

브랜치는 프로젝트 작업 트리의 버전입니다. 브랜치는 프로젝트 개발의 기초입니다. 새 프로젝트를 생성하면 GitLab은 리포지토리를 위한 기본 브랜치를 생성합니다. 기본 브랜치 설정은 프로젝트, 서브그룹, 그룹 또는 인스턴스에서 구성됩니다.

프로젝트가 성장함에 따라 팀은 더 많은 브랜치를 생성합니다. 각 브랜치는 변경 사항 집합을 나타내며, 이를 통해 병렬로 개발 작업을 수행할 수 있습니다. 한 브랜치에서의 개발 작업은 다른 브랜치에 영향을 미치지 않습니다.

브랜치의 개발 워크플로우는 다음과 같습니다:

  1. 브랜치 생성 및 추가 커밋. 이 프로세스를 간소화하려면 브랜치 이름 패턴을 따라야 합니다.
  2. 작업이 검토를 받을 준비가 되면, 변경 사항을 병합하기 위해 병합 요청을 생성합니다.
  3. 리뷰 앱으로 변경 사항 미리 보기.
  4. 리뷰 요청.
  5. 병합 요청이 승인되면 브랜치를 원래 브랜치에 병합합니다.
    병합 방법은 프로젝트에서 병합 요청이 처리되는 방식을 결정합니다.
  6. 브랜치의 내용이 병합된 후, 병합된 브랜치 삭제.

모든 브랜치 보기

GitLab 사용자 인터페이스에서 브랜치를 보고 관리하려면:

  1. 왼쪽 사이드바에서 검색하거나 이동을 선택하고 프로젝트를 찾습니다.
  2. 왼쪽 사이드바에서 코드 > 브랜치를 선택합니다.

이 페이지에서 할 수 있는 작업:

  • 모든 브랜치를 보거나, 활성 또는 오랜 브랜치만 필터링하여 보기.

    브랜치는 마지막 세 달 이내에 커밋이 이루어진 경우 활성으로 간주됩니다.
    그렇지 않으면 오랜 것으로 간주됩니다.

  • 새 브랜치 생성.
  • 브랜치 비교.
  • 병합된 브랜치 삭제.

  • 기본 브랜치를 가리키는 병합 요청 링크 보기.

    기본 브랜치가 아닌 브랜치에 병합 요청이 있는 경우 새 병합 요청 버튼이 표시됩니다.

  • 브랜치 규칙 보기.
  • 브랜치의 최신 파이프라인 상태 보기.

브랜치 생성

선행 조건:

  • 프로젝트에서 개발자 역할 이상을 가져야 합니다.

GitLab UI에서 새 브랜치를 생성하려면:

  1. 왼쪽 사이드바에서 검색하거나 이동을 선택하고 프로젝트를 찾습니다.
  2. 코드 > 브랜치를 선택합니다.
  3. 오른쪽 상단에서 새 브랜치를 선택합니다.
  4. 브랜치 이름을 입력합니다.
  5. 에서 만들기에서 브랜치의 기본이 되는 것을 선택합니다: 기존 브랜치, 기존 태그 또는 커밋 SHA.
  6. 브랜치 생성을 선택합니다.

빈 프로젝트에서

빈 프로젝트는 브랜치가 포함되어 있지 않지만, 추가할 수 있습니다.

선행 조건:

  • 프로젝트에서 개발자 역할 이상을 가져야 합니다.
  • 유지 관리자가 아니거나 소유자가 아닌 경우,
    기본 브랜치 보호
    은 부분적으로 보호됨 또는 보호되지 않음으로 설정되어야 커밋을
    기본 브랜치에 푸시할 수 있습니다.

빈 프로젝트에 기본 브랜치를 추가하려면:

  1. 왼쪽 사이드바에서 검색하거나 이동을 선택하고 프로젝트를 찾습니다.
  2. 이 프로젝트의 리포지토리는 비어 있습니다로 스크롤하고 추가할 파일 유형을 선택합니다.
  3. 웹 IDE에서 이 파일에 원하는 변경 사항을 적용한 후, 커밋 생성을 선택합니다.
  4. 커밋 메시지를 입력하고 커밋을 선택합니다.

GitLab은 기본 브랜치를 생성하고 해당 파일을 추가합니다.

이슈에서

이슈를 보면서 해당 페이지에서 직접 연관된 브랜치를 생성할 수 있습니다.

이렇게 생성된 브랜치는 이슈에서 브랜치 이름의 기본 패턴 구성을 사용하며, 변수도 포함됩니다.

전제 조건:

  • 프로젝트에 대해 최소한 개발자 역할이 있어야 합니다.

이슈에서 브랜치를 생성하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 계획 > 이슈를 선택하고 이슈를 찾습니다.
  3. 이슈 설명 아래에서 병합 요청 만들기 드롭다운 목록을 찾아 를 선택하여 드롭다운 목록을 표시합니다.
  4. 브랜치 만들기를 선택합니다. 기본 브랜치 이름이 이 프로젝트의 기본 패턴을 기반으로 제공됩니다. 원한다면 다른 브랜치 이름을 입력하세요.
  5. 브랜치 만들기를 선택하여 프로젝트의 기본 브랜치를 기반으로 브랜치를 생성합니다.

브랜치 이름 지정하기

Git은 브랜치 이름 규칙을 시행하여 브랜치 이름이 다른 도구와 호환되도록 유지하도록 돕습니다. GitLab은 브랜치 이름에 대해 추가 요구 사항을 추가하며, 잘 구성된 브랜치 이름에 대한 이점을 제공합니다.

GitLab은 모든 브랜치에 대해 이러한 추가 규칙을 시행합니다:

  • 브랜치 이름에 공백이 허용되지 않습니다.
  • 40개의 16진수 문자가 포함된 브랜치 이름은 금지됩니다. 이는 Git 커밋 해시와 유사하기 때문입니다.
  • 브랜치 이름은 대소문자를 구분합니다.

Docker와 같은 일반 소프트웨어 패키지는 추가 브랜치 이름 지정 제한 사항을 시행할 수 있습니다.

다른 소프트웨어 패키지와의 최상의 호환성을 위해 다음만 사용하십시오:

  • 숫자
  • 하이픈(-)
  • 밑줄(_)
  • ASCII 표준 테이블의 소문자

브랜치 이름에 슬래시(/)와 이모지를 사용할 수 있지만, 다른 소프트웨어 패키지와의 호환성을 보장할 수 없습니다.

특정 형식의 브랜치 이름은 추가 이점을 제공합니다:

이슈에서 브랜치 이름의 기본 패턴 구성

기본적으로 GitLab은 이슈에서 브랜치를 생성할 때 %{id}-%{title} 패턴을 사용하지만, 이 패턴을 변경할 수 있습니다.

전제 조건:

  • 프로젝트에 대해 최소한 유지 관리자 역할이 있어야 합니다.

이슈에서 생성된 브랜치의 기본 패턴을 변경하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 설정 > 리포지토리를 선택합니다.
  3. 브랜치 기본값을 확장합니다.
  4. 브랜치 이름 템플릿으로 스크롤하고 값을 입력합니다. 해당 필드는 다음 변수를 지원합니다:
    • %{id}: 이슈의 숫자 ID입니다.
    • %{title}: Git 브랜치 이름에 허용되는 문자만 사용하도록 수정된 이슈의 제목입니다.
  5. 변경 사항 저장을 선택합니다.

이슈 번호로 브랜치 이름 접두사 추가

병합 요청 생성을 간소화하려면 Git 브랜치 이름을 이슈 번호로 시작하고 하이픈을 추가하십시오.

예를 들어, 브랜치를 이슈 #123에 연결하려면 브랜치 이름을 123-로 시작하십시오.

이슈와 브랜치는 동일한 프로젝트에 있어야 합니다.

GitLab은 이슈 번호를 사용하여 병합 요청에 데이터를 가져옵니다:

  • 이슈가 병합 요청과 관련이 있음을 표시합니다. 이슈와 병합 요청은 서로 링크를 표시합니다.
  • 브랜치가 이슈와 연결됩니다.
  • 프로젝트가 기본 종료 패턴으로 구성되어 있는 경우, 병합 요청을 병합하면 관련 이슈를 자동으로 종료합니다.
  • 병합 요청이 동일한 프로젝트에 있고 포크가 아닌 경우, 이슈의 마일스톤과 레이블이 병합 요청으로 복사됩니다.

브랜치 관리 및 보호

GitLab은 개별 브랜치를 보호하기 위한 여러 방법을 제공합니다. 이러한 방법은 브랜치가 생성된 후 삭제되기까지 감독 및 품질 검사를 받을 수 있도록 보장합니다. 브랜치 보호를 보려면 및 수정하려면 브랜치 규칙을 참조하세요.

브랜치 비교

저장소에서 브랜치를 비교하려면:

  1. 왼쪽 사이드바에서 Search or go to를 선택하여 프로젝트를 찾습니다.
  2. Code > Compare revisions을 선택합니다.
  3. 원하는 브랜치를 찾기 위해 Source 브랜치를 선택합니다. 정확한 일치는 먼저 표시됩니다. 다음과 같은 연산자를 사용하여 검색을 세분화할 수 있습니다:
    • ^는 브랜치 이름의 시작과 일치합니다: ^feat는 feat/user-authentication와 일치합니다.
    • $는 브랜치 이름의 끝과 일치합니다: widget$는 feat/search-box-widget과 일치합니다.
    • *는 와일드카드를 사용하여 일치합니다: branch*cache*는 fix/branch-search-cache-expiration과 일치합니다.
    • 연산자를 조합할 수 있습니다: ^chore/*migration$는 chore/user-data-migration과 일치합니다.
  4. Target 저장소와 브랜치를 선택합니다. 정확한 일치는 먼저 표시됩니다.
  5. Show changes 아래에서 브랜치를 비교할 방법을 선택합니다:
    • Only incoming changes from source(기본값)는 소스 브랜치와 두 브랜치의 최신 공통 커밋 이후의 차이를 보여줍니다. 이 방법은 소스 브랜치가 생성된 후 타겟 브랜치에서 이루어진 관련 없는 변경 사항은 포함하지 않습니다. 이 방법은 git diff <from>...<to> Git 명령어를 사용합니다. 브랜치를 비교할 때 이 방법은 실제 커밋 대신 병합 기준을 사용하므로 체리픽된 커밋의 변경 사항이 새로운 변경 사항으로 표시됩니다.
    • Include changes to target since source was created는 두 브랜치 간의 모든 차이를 보여줍니다. 이 방법은 git diff <from> <to> Git 명령어를 사용합니다.
  6. Compare를 선택하여 커밋 목록 및 변경된 파일을 표시합니다.
  7. 선택 사항. Source와 Target을 반대로 하려면 Swap revisions( )를 선택합니다.

병합된 브랜치 삭제

병합된 브랜드는 모든 기준을 충족하는 경우 일괄 삭제할 수 있습니다:

  • 보호된 브랜치 protected branches가 아닙니다.
  • 프로젝트의 기본 브랜치에 병합되었습니다.

필수 조건:

  • 프로젝트에 대해 최소한 개발자 역할이 있어야 합니다.

이를 수행하려면:

  1. 왼쪽 사이드바에서 Search or go to를 선택하여 프로젝트를 찾습니다.
  2. Code > Branches를 선택합니다.
  3. 페이지 오른쪽 상단 모서리에서 More 를 선택합니다.
  4. Delete merged branches을 선택합니다.
  5. 대화 상자에서 ‘delete’라는 단어를 입력하여 확인한 후 Delete merged branches를 선택합니다.

타겟 브랜치에 대한 워크플로 구성

Tier: Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated
History

일부 프로젝트는 develop 및 qa와 같은 여러 장기 브랜치를 개발에 사용합니다.
이러한 프로젝트에서는 main을 기본 브랜치로 유지하고, 병합 요청이 develop 또는 qa를 대상으로 하기를 원할 수 있습니다.
타겟 브랜치 워크플로는 병합 요청이 프로젝트의 적절한 개발 브랜치를 목표로 삼도록 보장하는 데 도움을 줍니다.

병합 요청을 생성할 때 워크플로는 브랜치의 이름을 체크합니다.
브랜치 이름이 워크플로와 일치하면 병합 요청은 지정한 브랜치를 대상으로 합니다.
브랜치 이름이 일치하지 않으면 병합 요청은 프로젝트의 기본 브랜치를 대상으로 합니다.

규칙은 “첫 번째 일치” 기준으로 처리됩니다 - 두 개의 규칙이 동일한 브랜치 이름과 일치하는 경우, 가장 위의 규칙이 적용됩니다.

필수 조건:

  • 최소한 유지 관리자 역할이 있어야 합니다.

타겟 브랜치 워크플로를 생성하려면:

  1. 왼쪽 사이드바에서 Search or go to를 선택하여 프로젝트를 찾습니다.
  2. Settings > Merge requests를 선택합니다.
  3. Merge request branch workflow로 스크롤 다운합니다.
  4. Add branch target을 선택합니다.
  5. Branch name pattern에 브랜치 이름과 비교할 문자열 또는 와일드카드를 제공합니다.
  6. Branch name pattern과 브랜치 이름이 일치할 때 사용하는 Target branch를 선택합니다.
  7. Save를 선택합니다.

대상 브랜치 워크플로우 예시

당신은 프로젝트를 다음과 같은 대상 브랜치 워크플로우를 갖도록 구성할 수 있습니다:

브랜치 이름 패턴 대상 브랜치
feature/* develop
bug/* develop
release/* main

이러한 대상 브랜치는 다음과 같은 프로젝트에 대한 병합 요청을 생성하는 과정을 간소화합니다:

  • main을 애플리케이션의 배포 상태를 나타내기 위해 사용합니다.
  • develop와 같은 다른 장기 실행 브랜치에서 현재의 미발표 개발 작업을 추적합니다.

만약 당신의 워크플로우가 처음에 새 기능들을 main 대신 develop에 배치한다면, 이러한 대상 브랜치는 feature/* 또는 bug/*에 일치하는 모든 브랜치가 실수로 main을 대상으로 하지 않도록 보장합니다.

main으로 릴리즈할 준비가 되었을 때, release/*라는 이름의 브랜치를 생성하고 이 브랜치가 main을 대상으로 하도록 하세요.

대상 브랜치 워크플로우 삭제

대상 브랜치 워크플로우를 제거해도 기존의 병합 요청은 변경되지 않습니다.

전제 조건:

  • 최소한 Maintainer 역할이 필요합니다.

이를 수행하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 설정 > 병합 요청을 선택합니다.
  3. 삭제할 브랜치 대상을 선택하고 삭제를 클릭합니다.

관련 주제

문제 해결

동일한 커밋을 포함하는 여러 브랜치

더 깊은 기술적 차원에서 Git 브랜치는 별개의 개체가 아니라 일련의 커밋 SHA에 부착된 레이블입니다.

GitLab이 브랜치가 병합되었는지를 결정할 때, 특정 커밋 SHA의 존재를 위해 대상 브랜치를 확인합니다.

이 동작은 두 개의 병합 요청이 동일한 커밋을 포함할 때 예상치 못한 결과를 초래할 수 있습니다.

이 예시에서 브랜치 B와 C는 모두 브랜치 A의 동일한 커밋(3)에서 시작합니다:

%%{init: { "fontFamily": "GitLab Sans" }}%% gitGraph accTitle: 동일한 커밋을 가진 여러 브랜치 다이어그램 accDescr: 브랜치 A와 B는 동일한 커밋을 포함하지만 브랜치 B는 다른 커밋도 포함합니다. 브랜치 B를 병합하면 브랜치 A가 병합된 것으로 표시됩니다. 왜냐하면 브랜치 A의 모든 커밋이 병합되었기 때문입니다. commit id:"a" branch "branch A" commit id:"b" commit id:"c" type: HIGHLIGHT branch "branch B" commit id:"d" checkout "branch A" branch "branch C" commit id:"e" checkout main merge "branch B" id:"merges commits b, c, d"

브랜치 B를 병합하면 브랜치 A도 자동으로 병합된 것으로 나타납니다 (당신의 조치 없이) 왜냐하면 이제 브랜치 A의 모든 커밋이 대상 브랜치 main에 나타나기 때문입니다. 브랜치 C는 병합되지 않은 상태로 남아있으며, 커밋 5는 브랜치 A나 B의 일부가 아니기 때문입니다.

병합 요청 A는 새로운 커밋을 그 브랜치에 푸시하려고 해도 여전히 병합된 상태로 남아있습니다.

병합 요청 A의 변경 사항 중 미병합된 것이 있다면 (병합 요청 A의 일부가 아니기 때문) 이를 위해 새로운 병합 요청을 열어야 합니다.

오류: 모호한 HEAD 브랜치가 존재합니다

Git 2.16.0 이전 버전에서는 HEAD라는 이름의 브랜치를 생성할 수 있었습니다.

HEAD라는 이름의 이 브랜치는 Git이 활성(체크 아웃된) 브랜치를 설명하는 데 사용하는 내부 참조(또한 HEAD라고도 명명됨)와 충돌합니다. 이 명명 충돌은 리포지토리의 기본 브랜치를 업데이트하는 것을 방해할 수 있습니다:

오류: 기본 브랜치를 설정할 수 없습니다. 리포지토리에 'HEAD'라는 이름의 브랜치가 있습니까?

이 문제를 해결하려면:

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 코드 > 브랜치를 선택합니다.
  3. HEAD라는 이름의 브랜치를 검색합니다.
  4. 브랜치에 커밋되지 않은 변경 사항이 없는지 확인합니다.
  5. 브랜치 삭제를 선택한 다음 예, 브랜치 삭제를 선택합니다.

Git 버전 2.16.0 이상에서는 이 이름을 가진 브랜치 생성이 금지됩니다.

여러분이 작성한 모든 브랜치 찾기

프로젝트에서 작성한 모든 브랜치를 찾으려면 Git 리포지토리에서 다음 명령을 실행합니다:

git for-each-ref --format='%(authoremail) %(refname:short)' | grep $(git config --get user.email)

프로젝트의 모든 브랜스를 저자별로 정렬하여 총계를 얻으려면 Git 리포지토리에서 다음 명령을 실행합니다:

git for-each-ref --format='%(authoremail)'  | sort | uniq -c | sort -g