브랜치는 팀의 개발 작업을 체계적으로 정리하고 분리합니다. 여러 사람이 서로 다른 기능을 동시에 작업할 때, 브랜치는 변경 사항이 서로 충돌하는 것을 방지합니다. 각 브랜치는 새 기능을 구현하거나 버그를 수정하거나 아이디어를 실험하는 격리된 작업 공간 역할을 합니다.

브랜치를 사용하면 팀은 다음을 수행할 수 있습니다.

• 메인 코드베이스를 방해하지 않고 별도의 기능을 작업합니다.
• 제안된 변경 사항이 프로젝트의 나머지 부분에 영향을 주기 전에 검토합니다.
• 다른 작업에 영향을 주지 않고 문제가 있는 변경 사항을 롤백합니다.
• 통제되고 예측 가능한 방식으로 프로덕션에 변경 사항을 배포합니다.

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

1. 브랜치를 만들고 커밋을 추가합니다. 이 프로세스를 간소화하려면 브랜치 이름 패턴을 따라야 합니다.
2. 작업을 검토할 준비가 되면 브랜치의 변경 사항을 머지하자고 제안하는 머지 리퀘스트를 만듭니다.
3. 리뷰 앱으로 변경 사항을 미리 봅니다.
4. 리뷰를 요청합니다.
5. 머지 리퀘스트가 승인된 뒤 브랜치를 원본 브랜치에 머지합니다. 머지 방법에 따라 프로젝트에서 머지 리퀘스트를 처리하는 방식이 결정됩니다.
6. 브랜치의 내용이 머지된 뒤 머지된 브랜치를 삭제합니다.

모든 브랜치 보기#

GitLab 사용자 인터페이스에서 브랜치를 보고 관리하려면 다음 단계를 수행합니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Code > Branches를 선택합니다.

이 페이지에서 다음을 수행할 수 있습니다.

• 모든 브랜치를 보거나, 활성 브랜치 또는 오래된 브랜치만 표시되도록 필터링합니다.

  브랜치는 최근 3개월 이내에 커밋이 있으면 활성으로 간주됩니다. 그렇지 않으면 오래된 브랜치로 간주됩니다.

• 새 브랜치를 만듭니다.

• 머지된 브랜치를 삭제합니다.

• 기본 브랜치를 가리키는 머지 리퀘스트 링크를 봅니다.

  기본 브랜치를 가리키지 않는 머지 리퀘스트가 있는 브랜치에는 [merge-request] New 머지 리퀘스트 버튼이 표시됩니다.

• 브랜치 규칙을 봅니다.

• 브랜치의 최신 파이프라인 상태를 봅니다.

브랜치 만들기#

사전 요구 사항:

• 프로젝트에 대한 Developer, Maintainer 또는 Owner 권한이 있어야 합니다.

GitLab UI에서 새 브랜치를 만들려면 다음 단계를 수행합니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Code > Branches를 선택합니다.
3. 오른쪽 상단에서 New branch를 선택합니다.
4. Branch name을 입력합니다.
5. Create from에서 브랜치의 기준을 선택합니다. 기존 브랜치, 기존 태그, 커밋 SHA 중에서 선택할 수 있습니다.
6. Create branch를 선택합니다.

빈 프로젝트에서#

빈 프로젝트에는 브랜치가 없지만, 브랜치를 추가할 수 있습니다.

사전 요구 사항:

• 프로젝트에 대한 Developer, Maintainer 또는 Owner 권한이 있어야 합니다.
• Maintainer 또는 Owner 권한이 없으면 기본 브랜치에 커밋을 푸시하기 위해 기본 브랜치 보호가 Partially protected 또는 Not protected로 설정되어 있어야 합니다.

빈 프로젝트에 기본 브랜치를 추가하려면 다음 단계를 수행합니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. The repository for this project is empty까지 스크롤한 뒤 추가할 파일 유형을 선택합니다.
3. Web IDE에서 이 파일을 원하는 대로 수정한 다음 Create commit을 선택합니다.
4. 커밋 메시지를 입력하고 Commit을 선택합니다.

GitLab이 기본 브랜치를 만들고 그 브랜치에 파일을 추가합니다.

이슈에서#

이슈를 보는 중에 해당 페이지에서 바로 연관된 브랜치를 만들 수 있습니다. 이렇게 만든 브랜치는 변수를 포함해 이슈에서 브랜치 이름의 기본 패턴을 사용합니다.

사전 요구 사항:

• 프로젝트에 대한 Developer, Maintainer 또는 Owner 권한이 있어야 합니다.

이슈에서 브랜치를 만들려면 다음 단계를 수행합니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Plan > Work items를 선택하고, Type = Issue로 필터링한 뒤 이슈를 선택합니다.
3. 이슈 설명 아래에서 Create merge request [chevron-down] 를 선택해 드롭다운 목록을 표시합니다.
4. Create branch를 선택합니다.
5. 대화 상자의 Source (branch or tag) 드롭다운 목록에서 소스 브랜치나 태그를 선택합니다.
6. 제안된 브랜치 이름을 확인합니다. 이 이름은 프로젝트의 기본 브랜치 이름 패턴을 기준으로 만들어집니다.
7. 선택 사항. 다른 브랜치 이름을 사용해야 하면 Branch name 텍스트 상자에 입력합니다.
8. Create branch를 선택합니다.

빈 리포지터리에서 브랜치를 만드는 방법은 빈 리포지터리 동작을 참고합니다.

만든 브랜치의 이름에 이슈 번호가 접두사로 붙으면 GitLab이 이슈와 관련 머지 리퀘스트를 상호 연결합니다.

태스크에서#

사전 요구 사항:

• 프로젝트에 대한 Developer, Maintainer 또는 Owner 권한이 있어야 합니다.

태스크에서 바로 브랜치를 만들려면 다음 단계를 수행합니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Plan > Work items를 선택하고, Type = Task로 필터링한 뒤 태스크를 선택합니다.
3. 태스크 설명 아래에서 Create merge request [chevron-down] 를 선택해 드롭다운 목록을 표시합니다.
4. Create branch를 선택합니다.
5. 대화 상자의 Source branch or tag 드롭다운 목록에서 소스 브랜치나 태그를 선택합니다.
6. 제안된 브랜치 이름을 확인합니다. 이 이름은 프로젝트의 기본 브랜치 이름 패턴을 기준으로 만들어집니다.
7. 선택 사항. 다른 브랜치 이름을 사용해야 하면 Branch name 텍스트 상자에 입력합니다.
8. Create branch를 선택합니다.

빈 리포지터리에서 브랜치를 만드는 방법은 빈 리포지터리 동작을 참고합니다.

만든 브랜치의 이름에 태스크 번호가 접두사로 붙으면 GitLab이 이슈와 관련 머지 리퀘스트를 상호 연결합니다.

빈 리포지터리 동작#

Git 리포지터리가 비어 있으면 GitLab은 다음과 같이 동작합니다.

• 기본 브랜치를 만듭니다.
• 빈 README.md 파일을 커밋합니다.
• 이슈 제목을 기반으로 새 브랜치를 만들고 그 브랜치로 리디렉션합니다.
• 프로젝트가 Kubernetes 같은 배포 서비스로 구성되어 있으면 GitLab이 .gitlab-ci.yml 파일을 만들도록 도와주면서 자동 배포를 설정하라고 안내합니다.

브랜치 이름 지정#

Git은 브랜치 이름이 다른 도구와 계속 호환되도록 브랜치 이름 규칙을 적용합니다. GitLab은 브랜치 이름에 추가 요구 사항을 두고, 잘 구조화된 브랜치 이름에 이점을 제공합니다.

GitLab은 모든 브랜치에 다음 추가 규칙을 적용합니다.

• 브랜치 이름에는 공백을 사용할 수 없습니다.
• 16진수 문자 40개로 이루어진 브랜치 이름은 Git 커밋 해시와 비슷하기 때문에 금지됩니다.
• 브랜치 이름은 대소문자를 구분합니다.

특정 형식을 갖춘 브랜치 이름은 다음을 제공합니다.

• 간소화된 머지 리퀘스트 워크플로. 브랜치 이름 앞에 이슈 번호를 붙이면 적용됩니다.
• 브랜치 이름을 기반으로 하는 자동 브랜치 보호.
• 브랜치가 GitLab에 푸시되기 전에 브랜치 이름을 테스트하는 푸시 규칙.
• 머지 리퀘스트에서 실행되는 CI/CD job 제어.

소프트웨어 패키지#

Docker 같은 일반적인 소프트웨어 패키지는 추가 브랜치 이름 제한을 적용할 수 있습니다.

다른 소프트웨어 패키지와의 호환성을 가장 높이려면 다음만 사용합니다.

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

브랜치 이름에서 피해야 할 문자#

Git은 기술적으로 브랜치 이름에 많은 문자를 허용하지만, 특정 문자는 GitLab Runner 및 다른 도구에서 문제를 일으킬 수 있어 권장하지 않습니다.

• 공백과 공백 문자
• 특수 경로 또는 glob(와일드카드) 문자: ~, ^, :, ?, *, [, \, ', "
• 이중 점: ..
• 특수 Git 구문: @{
• 연속 슬래시: //
• 이모지
• 끝에 오는 . 또는 .lock 접미사
• - 또는 .로 시작
• ASCII 제어 문자(Delete 포함)

GitLab Runner 및 다른 도구와의 호환성을 최대로 하려면 영숫자, 하이픈, 밑줄만 사용합니다.

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

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

사전 요구 사항:

• 프로젝트에 대한 Maintainer 또는 Owner 권한이 있어야 합니다.

이슈에서 만든 브랜치의 기본 패턴을 변경하려면 다음 단계를 수행합니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > Repository를 선택합니다.
3. Branch defaults를 확장합니다.
4. Branch name template까지 스크롤한 뒤 값을 입력합니다. 이 필드는 다음 변수를 지원합니다.
   • %{id}: 이슈의 숫자 ID입니다.
   • %{title}: 이슈의 제목으로, Git 브랜치 이름에서 허용되는 문자만 사용하도록 수정됩니다.
   • %{branch_creator}: 브랜치를 만드는 사용자의 사용자 이름으로, Git 브랜치 이름에서 허용되는 문자만 사용하도록 수정됩니다.
5. Save changes를 선택합니다.

브랜치 이름 앞에 숫자 붙이기#

머지 리퀘스트 생성을 간소화하려면 Git 브랜치 이름을 이슈 또는 태스크 번호로 시작하고 그 뒤에 하이픈을 붙입니다. 예를 들어 브랜치를 이슈 #123에 연결하려면 브랜치 이름을 123-으로 시작합니다.

브랜치는 이슈 또는 태스크와 같은 프로젝트에 있어야 합니다.

GitLab은 이 번호를 사용해 머지 리퀘스트로 데이터를 가져옵니다.

• 항목이 머지 리퀘스트와 관련된 것으로 표시되고 서로에 대한 링크가 표시됩니다.
• 브랜치가 이슈 또는 태스크에 연결됩니다.
• 프로젝트에 기본 닫기 패턴이 구성되어 있으면, 머지 리퀘스트를 머지할 때 관련 이슈도 자동으로 닫힙니다.
• 머지 리퀘스트가 같은 프로젝트에 있고 포크가 아니면, 이슈의 마일스톤과 레이블이 머지 리퀘스트로 복사됩니다.

브랜치 관리 및 보호#

GitLab은 개별 브랜치를 보호하는 여러 방법을 제공합니다. 이러한 방법은 브랜치가 생성된 때부터 삭제될 때까지 감독과 품질 검사를 받도록 합니다. 브랜치 보호를 보고 편집하려면 브랜치 규칙을 참고합니다.

브랜치 비교 다운로드#

브랜치 간 비교를 GitLab 외부에서 사용하기 위해 diff 또는 패치 파일로 다운로드할 수 있습니다.

Diff로#

브랜치 비교를 diff로 다운로드하려면 비교 URL에 format=diff를 추가합니다.

• URL에 쿼리 매개변수가 없으면 ?format=diff를 덧붙입니다.

  https://gitlab.example.com/my-group/my-project/-/compare/main...feature-branch?format=diff
  

• URL에 이미 쿼리 매개변수가 있으면 &format=diff를 덧붙입니다.

  https://gitlab.example.com/my-group/my-project/-/compare/main...feature-branch?from_project_id=2&format=diff
  

diff를 다운로드해 적용하려면 다음 명령을 실행합니다.

curl "https://gitlab.example.com/my-group/my-project/-/compare/main...feature-branch?format=diff" | git apply

패치 파일로#

브랜치 비교를 패치 파일로 다운로드하려면 비교 URL에 format=patch를 추가합니다.

• URL에 쿼리 매개변수가 없으면 ?format=patch를 덧붙입니다.

  https://gitlab.example.com/my-group/my-project/-/compare/main...feature-branch?format=patch
  

• URL에 이미 쿼리 매개변수가 있으면 &format=patch를 덧붙입니다.

  https://gitlab.example.com/my-group/my-project/-/compare/main...feature-branch?from_project_id=2&format=patch
  

git am으로 패치를 다운로드해 적용하려면 다음 명령을 실행합니다.

# Download and preview the patch
curl "https://gitlab.example.com/my-group/my-project/-/compare/main...feature-branch?format=patch" > changes.patch
git apply --check changes.patch

# Apply the patch
git am changes.patch

한 번의 명령으로 패치를 다운로드해 적용할 수도 있습니다.

curl "https://gitlab.example.com/my-group/my-project/-/compare/main...feature-branch?format=patch" | git am

머지된 브랜치 삭제#

머지된 브랜치는 다음 조건을 모두 충족하면 일괄 삭제할 수 있습니다.

• 보호된 브랜치가 아닙니다.
• 프로젝트의 기본 브랜치로 머지되었습니다.

사전 요구 사항:

• 프로젝트에 대한 Developer, Maintainer 또는 Owner 권한이 있어야 합니다.

이를 수행하려면 다음 단계를 따릅니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Code > Branches를 선택합니다.
3. 페이지 오른쪽 상단에서 More ⋮ 를 선택합니다.
4. Delete merged branches를 선택합니다.
5. 대화 상자에 delete를 입력해 확인한 다음 Delete merged branches를 선택합니다.

대상 브랜치 워크플로 구성#

일부 프로젝트는 develop과 qa처럼 개발에 여러 장기 브랜치를 사용합니다. 이러한 프로젝트에서는 main을 기본 브랜치로 유지하면서 머지 리퀘스트는 develop이나 qa를 대상으로 하기를 기대할 수 있습니다. 대상 브랜치 워크플로는 머지 리퀘스트가 프로젝트에 적합한 개발 브랜치를 대상으로 하도록 도와줍니다.

머지 리퀘스트를 만들면 워크플로가 브랜치의 이름을 확인합니다. 브랜치 이름이 워크플로와 일치하면 머지 리퀘스트는 지정한 브랜치를 대상으로 합니다. 브랜치 이름이 일치하지 않으면 머지 리퀘스트는 프로젝트의 기본 브랜치를 대상으로 합니다.

규칙은 "첫 번째 일치" 기준으로 처리됩니다. 두 규칙이 같은 브랜치 이름에 일치하면 가장 위에 있는 규칙이 적용됩니다.

사전 요구 사항:

• Maintainer 또는 Owner 권한이 있어야 합니다.

대상 브랜치 워크플로를 만들려면 다음 단계를 수행합니다.

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를 선택합니다.

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

프로젝트에 다음과 같은 대상 브랜치 워크플로를 구성할 수 있습니다.

이러한 대상 브랜치는 다음과 같은 프로젝트에서 머지 리퀘스트를 만드는 과정을 단순화합니다.

• 애플리케이션의 배포 상태를 나타내는 데 main을 사용합니다.
• develop처럼 장기간 유지되는 다른 브랜치에서 아직 릴리스되지 않은 현재 개발 작업을 추적합니다.

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

main으로 릴리스할 준비가 되면 release/*라는 이름의 브랜치를 만들고, 이 브랜치가 main을 대상으로 하도록 합니다.

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

대상 브랜치 워크플로를 제거해도 기존 머지 리퀘스트는 변경되지 않습니다.

사전 요구 사항:

• Maintainer 또는 Owner 권한이 있어야 합니다.

이를 수행하려면 다음 단계를 따릅니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > Merge requests를 선택합니다.
3. 삭제하려는 브랜치 대상에서 Delete를 선택합니다.

관련 주제#

• 보호된 브랜치
• 브랜치 규칙
• 리비전 비교
• 머지 리퀘스트의 변경 사항 비교
• 머지 리퀘스트 변경 사항 다운로드
• Branches API
• Protected branches API
• Git 시작하기
• Branches in a Nutshell

문제 해결#

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

기술적으로 더 깊이 들어가면, Git 브랜치는 별개의 엔터티가 아니라 커밋 SHA 집합에 붙은 레이블입니다. GitLab은 브랜치가 머지되었는지 판단할 때 대상 브랜치에 그 커밋 SHA가 존재하는지 확인합니다. 이 동작은 두 머지 리퀘스트가 같은 커밋을 포함할 때 예상하지 못한 결과를 낳을 수 있습니다. 이 예시에서 브랜치 B와 C는 모두 브랜치 A의 같은 커밋(3)에서 시작합니다.

%%{init: { "fontFamily": "GitLab Sans" }}%%
gitGraph
    accTitle: Diagram of multiple branches with the same commit
    accDescr: Branches A and B contain the same commit, but branch B also contains other commits. Merging branch B makes branch A appear as merged, because all its commits are merged.
    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의 모든 커밋이 이제 대상 브랜치 main에 나타나므로 브랜치 A도 (별도의 조치 없이) 머지된 것으로 표시됩니다. 커밋 5는 브랜치 A나 B에 포함되지 않았기 때문에 브랜치 C는 머지되지 않은 상태로 남습니다.

머지 리퀘스트 A는 해당 브랜치에 새 커밋을 푸시하려고 해도 머지된 상태로 남습니다. 머지 리퀘스트 A의 변경 사항 중 (머지 리퀘스트 A에 포함되지 않아) 머지되지 않은 것이 남아 있으면, 그 변경 사항에 대해 새 머지 리퀘스트를 엽니다.

오류: 모호한 HEAD 브랜치가 존재함#

Git 2.16.0 이전 버전에서는 HEAD라는 이름의 브랜치를 만들 수 있었습니다. 이 HEAD 브랜치는 Git이 활성(체크아웃된) 브랜치를 나타내는 데 사용하는 내부 참조(이름도 HEAD)와 충돌합니다. 이 이름 충돌은 리포지터리의 기본 브랜치를 업데이트하지 못하게 만들 수 있습니다.

Error: Could not set the default branch. Do you have a branch named 'HEAD' in your repository?

이 문제를 해결하려면 다음 단계를 수행합니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Code > Branches를 선택합니다.
3. HEAD라는 이름의 브랜치를 검색합니다.
4. 해당 브랜치에 커밋되지 않은 변경 사항이 없는지 확인합니다.
5. Delete branch를 선택한 다음 Yes, delete branch를 선택합니다.

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

오류: Failed to create branch 4:Deadline Exceeded#

이 오류는 Gitaly의 타임아웃 때문에 발생합니다. 브랜치 생성이 구성된 타임아웃 기간보다 오래 걸릴 때 발생합니다.

이 문제를 해결하려면 다음 중 하나를 선택합니다.

• 시간이 오래 걸리는 서버 훅을 비활성화합니다.
• Gitaly 타임아웃 설정을 늘립니다.