Git 브랜치와 병합

브랜치를 사용하면 하나의 프로젝트에서 여러 작업 흐름을 서로 방해하지 않고 병행할 수 있습니다. 이 글에서는 브랜치가 무엇이고 왜 필요한지 살펴본 뒤, 브랜치를 만들고 전환하는 방법, 변경 사항을 병합하는 방법, IDE 도구로 병합 충돌을 차분히 해결하는 방법을 익힙니다. Claude Code가 저장소의 별도 브랜치에서 작업할 때 무엇을 하는지 이해하는 데 꼭 필요한 기본 내용입니다.

예시와 화면 캡처는 JetBrains IDE 기준이며, 메뉴 이름과 위치는 사용 중인 버전에 따라 다를 수 있습니다. 연습에는 별도의 학습용 저장소를 사용하세요. 실제 프로젝트에서는 해당 프로젝트의 브랜치, 커밋, 푸시 규칙을 따르세요.

브랜치란 무엇이며 왜 필요할까요

브랜치는 별도의 커밋 흐름에 붙이는 이름입니다. 브랜치를 만든다고 프로젝트 폴더가 복사되거나 커밋하지 않은 파일이 저장되는 것은 아닙니다. 일반적인 작업 폴더에서 브랜치를 전환하면 Git은 선택한 브랜치에 맞춰 파일을 바꿉니다. 아직 커밋하지 않은 변경 사항은 함께 따라오거나 전환을 막을 수 있습니다.

기본 브랜치인 main에서 별도의 개발 흐름을 위한 새 브랜치 feature/new-idea가 갈라져 나옵니다. 작업이 끝나면 변경 사항을 다시 main에 병합합니다.

프로젝트를 크게 손보거나 위험 부담이 있는 실험을 하고 싶다고 가정해 보세요. Git이 없다면 어떻게 할까요? 아마 프로젝트 전체를 새 폴더에 복사한 다음 그 복사본에서 작업할 겁니다. 결과가 마음에 들면 원래 폴더로 옮기고, 그렇지 않으면 복사본을 지우겠죠.

복사본에 빗대면 서로 다른 작업 흐름을 이해하기 쉽지만, 기술적으로 브랜치는 커밋을 가리키는 포인터입니다. 책을 예로 들어볼까요?

1. 완성된 원고가 있습니다. 이 원고가 기본 브랜치 main입니다;
2. 다른 결말을 써보고 싶어 새 브랜치, 예를 들어 feature/new-idea를 만듭니다;
3. 새 브랜치에서 작업하면서 원고의 본문은 그대로 둡니다;
4. 새 결말이 더 마음에 들면 기존 결말을 바꿉니다. 브랜치를 merge하는 과정입니다;
5. 필요 없어진 결말이 담긴 오래된 초안은 브랜치를 삭제해 정리할 수 있습니다.

브랜치 만들고 작업하기

1단계. 브랜치 관리 메뉴를 여세요.

프로젝트 이름 옆의 기본 도구 모음에는 현재 브랜치 이름을 보여 주는 위젯이 있습니다. 기본값은 main입니다. 위젯을 클릭하고 + New Branch를 선택하세요.

2단계. 새 브랜치 이름을 정하세요.

브랜치 이름은 해결하려는 작업을 드러내도록 짓는 편이 좋습니다. 예를 들어 feature/add-usage-examples처럼요.

만들 때 Checkout branch를 선택하면 IDE가 새 브랜치로 전환합니다. 파일을 편집하기 전에 위젯에서 브랜치 이름을 확인하세요.

3단계. 변경 사항을 적용하고 커밋하세요.

README.md에 사용 예시 섹션을 추가하세요. 변경 사항을 검토한 다음 평소처럼 commit하면 새 브랜치의 기록에 저장된 스냅샷이 생깁니다.

브랜치 전환하기

사용 예시 변경 사항은 이제 feature/add-usage-examples 브랜치에 안전하게 저장되어 있습니다. 기본 브랜치 main으로 돌아가 어떤 상태인지 살펴보겠습니다.

1단계. 왼쪽 상단에서 현재 브랜치 이름이 표시된 위젯을 다시 클릭하세요.

2단계. Local 또는 Recent 목록에서 main 브랜치를 선택하고, 나타나는 하위 메뉴에서 Checkout을 클릭하세요.

3단계. 결과를 확인하세요.

전환한 다음 README.md 파일을 열어 보세요. 사용 예시 섹션이 보이지 않을 텐데, 다른 브랜치에 남아 있기 때문입니다. 이렇게 하면 main 브랜치의 안정적인 버전에 영향을 주지 않고 새로운 기능을 작업할 수 있습니다.

브랜치 병합

merge는 선택한 브랜치의 기록을 현재 브랜치에 합칩니다. 브랜치가 갈라진 뒤 main에 새 커밋이 없다면 fast-forward가 가능합니다. 이 경우 새 커밋을 만들지 않고 main이 C3으로 이동합니다. 두 작업 흐름이 서로 달라졌다면 일반 병합으로 부모가 두 개인 커밋을 만듭니다.

여기처럼 기록이 직선으로 이어진 경우 main은 C3으로 이동할 수 있습니다. feature/add-usage-examples 브랜치도 현재 C3을 가리킵니다. 병합을 위해 브랜치 이름을 삭제할 필요는 없습니다.

이제 feature/add-usage-examples 브랜치에서 작업을 마쳤고, 변경 사항을 기본 프로젝트에 반영하려 합니다.

1단계. 대상 브랜치로 전환하세요.

변경 사항을 추가할 대상, 즉 받는 쪽 브랜치에 있는지 확인하세요. 여기서는 main입니다.

2단계. 병합하세요.

브랜치 관리 위젯을 다시 클릭하세요. 목록에서 변경 사항을 가져올 보내는 쪽 브랜치(feature/add-usage-examples)를 선택한 다음 하위 메뉴에서 Merge 'feature/add-usage-examples' into 'main'을 선택하세요.

3단계. 결과를 확인하세요.

이제 main 브랜치의 README.md 파일에 새 예시 섹션이 추가되었습니다. 작업 내용을 프로젝트의 기본 버전에 성공적으로 병합했습니다.

병합 충돌

충돌은 Git이 변경 사항을 자동으로 병합하지 못했다는 뜻입니다. 같은 줄을 서로 다르게 수정한 경우가 흔하고, 한 브랜치에서 파일을 삭제하는 동안 다른 브랜치에서 그 파일을 수정한 경우에도 발생할 수 있습니다. 어떤 쪽을 택할지는 원하는 결과에 따라 결정합니다.

여기서 IDE(CLion 또는 IntelliJ IDEA)에 내장된 도구가 제 역할을 합니다. 터미널에서 충돌을 해결하는 일은 그리 편하지 않지만, 내장된 3-way merge 도구를 사용하면 과정을 한눈에 보면서 간단히 해결할 수 있습니다.

두 브랜치 모두 공통 조상 C1 이후에 각자 새 커밋이 생겼습니다. 기록이 갈라졌다고 해서 반드시 충돌이 생기는 것은 아닙니다. Git이 변경 사항을 자동으로 합칠 수 없을 때 충돌이 발생합니다. 아래 연습에서는 서로 다른 문구로 같은 원본 줄을 바꿉니다.

충돌 상황을 직접 만들어 보겠습니다.

1. main 브랜치에 있는지 확인하고 Commit 창에 커밋하지 않은 변경 사항이나 새 파일이 없는지 살펴보세요;
2. 새 브랜치 feature/new-title를 만들되, 아직 전환하지 마세요. Checkout branch 체크 표시가 해제되어 있는지 확인하세요;
3. main 브랜치에서 README.md의 첫 줄을 "나의 멋진 프로젝트"로 바꾸고 commit하세요;
4. feature/new-title 브랜치로 전환하세요. 이 브랜치의 README.md 첫 줄은 브랜치를 만든 시점의 예전 내용 그대로일 겁니다. 같은 줄을 "나의 최고 프로젝트"로 바꾸고 commit하세요;
5. main 브랜치로 돌아가 feature/new-title를 병합하세요.

이제 Git은 두 기록에서 같은 부분이 수정된 것을 확인하고, 충돌 해결 창(Merge Conflicts)을 표시합니다.

Merge 버튼을 눌러 충돌 해결 도구를 여세요. 여기에는 다음이 표시됩니다.

• 왼쪽 (Your changes) - 현재 브랜치, 즉 변경 사항을 병합받는 main의 파일 버전입니다;
• 오른쪽 (Changes from branch) - 현재 브랜치에 병합할 브랜치의 파일 버전입니다;
• 가운데 (Result) - 직접 구성해야 하는 최종 파일 버전입니다.

화살표 >> 또는 <<를 눌러 한쪽 변경 사항을 통째로 적용할 수 있습니다. 취소하려면 X 표시를 누르세요. 가운데 패널에 올바른 내용을 직접 입력해도 됩니다.

가운데 패널의 결과를 확인하고 Apply 또는 해당 완료 버튼을 누르세요. 그런 다음 Git 상태를 확인하세요. 병합이 아직 기록되지 않았다면 IDE에서 커밋합니다. 충돌 난 줄을 해결하는 것과 merge를 마무리하는 것은 별개의 단계입니다. 결과 코드가 예상대로 작동하는지도 확인하세요.

충돌이 발생하지 않을 때

연습 중 충돌이 생기지 않았다면 두 번째 브랜치가 어떤 커밋에서 만들어졌는지, 양쪽에서 같은 줄을 서로 다르게 바꿨는지 확인하세요. Git은 브랜치가 갈라진 뒤에도 서로 호환되는 변경 사항은 자동으로 병합할 수 있습니다. 또 다른 경우는 기록이 한 줄로 이어져 fast-forward가 가능한 상황입니다.

예를 들어:

1. main에 커밋 하나가 있다고 합시다(C1);
2. main 브랜치에서 "나의 멋진 프로젝트"라는 내용으로 새 커밋을 만듭니다. 이제 main은 C2를 가리킵니다;
3. 현재 main을 기준으로 feature/new-title 브랜치를 만듭니다. 새 브랜치도 C2에서 시작합니다;
4. feature/new-title에서 "나의 최고 프로젝트"라는 내용으로 커밋합니다. 이 브랜치는 앞으로 나아가 C3을 가리킵니다;
5. 아직 C2를 가리키는 main으로 돌아와 feature/new-title를 병합합니다.

Git은 main이 feature/new-title의 직접적인 조상임을 확인합니다. 다른 브랜치에서 작업하는 동안 main의 기록에는 새 커밋이 없었습니다. 따라서 충돌 없이 main 포인터를 C3까지 앞으로 이동합니다.

main의 기록이 갈라지지 않고 feature/new-title의 기록으로 이어집니다. 그래서 Git은 main을 앞으로 이동할 뿐이며 충돌은 발생하지 않습니다.

변경 기록 살펴보기

프로젝트에서 어떤 일이 있었는지 더 잘 파악하려면 기록을 살펴보는 것이 좋습니다.

Git 도구 창을 여세요. 보통 IDE 왼쪽 도구 모음이나 창 아래쪽에 아이콘이 있습니다. Git 도구 모음에서 Log 또는 Show Git Log 탭을 선택하세요. 모든 브랜치와 커밋이 그래프로 표시됩니다. 어떤 브랜치가 어디서 갈라졌고 어디서 병합됐는지 한눈에 확인할 수 있습니다.

커밋을 클릭하면 어떤 변경 사항이 포함됐는지, 누가 언제 만들었는지 확인할 수 있습니다. 코드 기록을 되짚어 보는 타임머신 같은 기능이죠.

Claude Code와 함께 사용할 때

브랜치를 이해하면 Claude Code가 저장소에서 작업할 때 수행하는 동작도 더 쉽게 파악할 수 있습니다. Claude Code가 브랜치를 활용해 하는 일과 눈여겨볼 점은 다음과 같습니다.

• 작업과 프로젝트 규칙에서 정해 둔 경우 별도 브랜치를 만듭니다;
• 중요한 시점에 commit을 제안합니다. diff를 읽고 그대로 진행할지 수정할지 결정하세요;
• 필요한 저장된 커밋을 찾고, 커밋하지 않은 변경 사항을 고려해 되돌리는 방법을 선택하도록 돕습니다;
• 병합 충돌이 생기면 도움을 요청할 수 있습니다. IDE의 같은 도구로 해결하면 됩니다;
• pull request도 준비하고 설명을 작성할 수 있습니다. PR은 브랜치를 기본 브랜치에 병합해 달라는 제안이며, 예를 들어 GitHub CLI로 만들 수 있습니다.

이전 글: Git 일상 작업 흐름 · 다음 글: Pull request 생성부터 병합까지