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

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

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

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

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

모든 브랜치 보기#

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

1. 상단 바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Code > Branches를 선택합니다.

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

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

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

• 새 브랜치를 만듭니다.

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

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

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

• 브랜치 규칙 보기.

• 브랜치의 최신 파이프라인 상태 확인.

브랜치 만들기#

사전 요구 사항:

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

GitLab UI에서 새 브랜치를 만들려면:

1. 상단 바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
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. 상단 바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
2. 이 프로젝트의 리포지터리가 비어 있습니다까지 스크롤하고 추가할 파일 유형을 선택합니다.
3. Web IDE에서 이 파일에 원하는 변경을 하고 Create commit을 선택합니다.
4. 커밋 메시지를 입력하고 Commit을 선택합니다.

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

이슈에서#

이슈를 볼 때 해당 페이지에서 직접 관련 브랜치를 만들 수 있습니다. 이 방법으로 만든 브랜치는 변수를 포함한 이슈에서 브랜치 이름의 기본 패턴을 사용합니다.

사전 요구 사항:

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

이슈에서 브랜치를 만들려면:

1. 상단 바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
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. 상단 바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
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은 모든 브랜치에 다음 추가 규칙을 적용합니다:

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

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

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

소프트웨어 패키지#

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

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

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

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

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

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

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

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

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

사전 요구 사항:

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

이슈에서 만든 브랜치의 기본 패턴을 변경하려면:

1. 상단 바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Settings > Repository를 선택합니다.
3. Branch defaults를 확장합니다.
4. Branch name template까지 스크롤하여 값을 입력합니다. 필드는 다음 변수를 지원합니다:
   • %{id}: 이슈의 숫자 ID.
   • %{title}: 이슈의 제목으로, 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. 상단 바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Code > Branches를 선택합니다.
3. 페이지 오른쪽 상단 모서리에서 More ⋮를 선택합니다.
4. Delete merged branches를 선택합니다.
5. 대화 상자에서 delete를 입력하여 확인하고 Delete merged branches를 선택합니다.

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

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

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

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

사전 요구 사항:

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

대상 브랜치 워크플로를 만들려면:

1. 상단 바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
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. 상단 바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
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도 (사용자 조치 없이) 머지된 것으로 표시됩니다. 브랜치 A의 모든 커밋이 이제 대상 브랜치 main에 나타나기 때문입니다. 브랜치 C는 커밋 5가 브랜치 A 또는 B의 일부가 아니었기 때문에 머지되지 않은 상태로 남아 있습니다.

머지 리퀘스트 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. 상단 바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
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 타임아웃 설정을 늘립니다.