교육 / GitHub 가이드 / 7편

브랜치 분기와 충돌 대처

읽는 시간: 약 10분 · 버전: v0.3 (2026-09-21) · GitHub 가이드 7편
지금 충돌(conflict) 안내가 떠 있다면 아래 "3. 충돌 발생 시 대처"부터 보세요. 1~2절은 "왜 그런 일이 생기는지"를 설명합니다.

1. 브랜치의 분기

0편에서는 브랜치를 "기록의 줄"이라고만 했습니다. 조금 더 정확히 말하면, 브랜치는 어느 한 시점의 상태를 그대로 복사해서 갈라져 나온 줄기입니다. 보고서로 치면, 어제 날짜의 최종본을 복사해 "수정 작업용"으로 따로 고치기 시작하는 것과 같습니다.

main에서 work가 갈라져 나온 뒤 두 흐름이 따로 자라는 그림. 자동으로는 서로 넘어가지 않고, work에서 main으로는 작업, 커밋, PR 생성, 검토 후 main 반영의 순서로만 들어간다

핵심은 하나입니다. 브랜치를 나누면 두 흐름은 자동으로 서로 반영되지 않습니다.

  • 분기점: work 는 main 의 어느 한 시점에서 갈라져 나왔습니다. 그 시점까지의 이력은 둘이 똑같습니다.
  • 갈라진 뒤에는 따로 자랍니다. work 에 커밋을 쌓아도 main 은 그대로입니다.
  • work → main: ① 작업 → ② 커밋 → ③ PR 생성 → ④ 검토 후 main 반영. PR은 "반영해 달라는 요청"이고, 반영은 검토가 끝난 뒤에 일어나는 별개의 단계입니다. PR을 만들었다고 main 이 바뀌지는 않습니다.
  • main 은 직접 고치지 않습니다 (우리 TF 원칙). 팀장도 마찬가지입니다. main 은 PR이 병합될 때만 바뀌므로, main 에 있는 내용은 모두 work 에서 간 것입니다. 그래서 병합이 끝난 뒤에 work 를 main 에 맞추는 작업은 필요 없습니다. 같은 work 에서 평소 순서대로 계속 작업하면 됩니다.

일반적인 개발 방식과 우리 TF의 차이

개발자들은 보통 기능 하나를 만들 때마다 main 에서 새 브랜치를 따서(예: feature/login) 작업하고, 병합이 끝나면 그 브랜치를 지웁니다. 여러 사람이 서로 방해하지 않고 동시에 일하기 위해서입니다. AI가 가끔 "새 브랜치를 만들까요?"라고 묻는 것도 이 관행 때문입니다.

우리 TF는 그렇게 하지 않습니다. 프로젝트마다 작업자가 한 명이라 줄기를 여러 개 둘 이유가 없고, 브랜치를 만들고 고르고 지우는 일이 늘어날수록 실수할 곳도 늘어나기 때문입니다. 그래서 work 하나를 계속 쓰는 것이 우리 TF의 규칙입니다. 나중에 한 프로젝트를 여러 명이 함께 하게 되면 그때 팀장이 방식을 안내합니다.

용어 주의: 포크(fork)는 다른 말입니다. 브랜치는 같은 저장소 안에서 줄기를 나누는 것이고, 포크는 저장소를 통째로 다른 계정에 복사하는 것입니다. 우리 TF에서 포크는 금지입니다(5편). "브랜치를 딴다", "분기한다"와 "포크한다"를 섞어 쓰지 않습니다.

2. 충돌의 원인

두 줄기를 합칠 때 Git은 양쪽의 변경을 자동으로 합칩니다. 대부분은 문제없이 끝납니다. 같은 파일의 같은 곳을 양쪽에서 다르게 고쳤을 때만 Git이 멈춥니다. 이것이 충돌(conflict) 입니다.

다른 곳을 고쳤을 때는 자동으로 합쳐지고, 같은 곳을 다르게 고쳤을 때만 충돌이 난다는 것을 비교한 그림

충돌은 고장이 아닙니다. "둘 중 어느 쪽이 맞는지 사람이 정해 주세요"라는 Git의 질문입니다. 다만 잘못 답하면 한쪽의 작업이 조용히 사라지기 때문에 신중해야 합니다.

충돌이 발생할 수 있는 상황

main 을 직접 고치지 않고 work 를 혼자 쓰는 우리 방식에서는 충돌이 드뭅니다. 생긴다면 아래 중 하나입니다.

언제왜어디에 나타나나
Revert 를 했을 때 (가장 흔함)되돌리려는 커밋이 고친 곳을 그 뒤의 커밋이 또 고쳤습니다GitHub Desktop에 충돌 창
Pull origin 을 눌렀을 때GitHub 쪽 work 에 내 PC에 없는 커밋이 있고(예: 팀장이 도와주려고 work 에 수정을 넣어 줌, 다른 PC에서 작업함), 내 PC의 아직 푸시하지 않은 커밋이 같은 곳을 고쳤습니다GitHub Desktop에 충돌 창
PR을 만들었을 때연습장처럼 여러 사람의 PR이 같은 main 으로 들어가는 저장소에서, 다른 사람이 같은 파일을 먼저 고쳤습니다. 혼자 쓰는 실제 프로젝트에서는 main 을 직접 고치지 않으므로 거의 생기지 않습니다브라우저의 PR 화면에 "conflicts" 안내

충돌은 아니지만 비슷하게 막히는 경우도 있습니다. 커밋하지 않은 변경이 있는 채로 Pull을 하거나 브랜치를 바꾸려 하면, GitHub Desktop이 그 변경을 어떻게 할지 묻습니다. 그래서 Pull은 작업을 시작할 때(Changes가 비어 있을 때) 합니다.

3. 충돌 발생 시 대처

GitHub Desktop의 충돌 창을 단순하게 그린 그림과 네 단계: 멈춘다, 캡처한다, Abort merge를 누른다, 팀장에게 알린다

GitHub Desktop의 충돌 창 (Pull, Revert)

  1. 멈춥니다. AI(Codex)에게 작업을 더 시키지 않습니다. "충돌을 해결해 줘"라고도 시키지 않습니다.
  2. 화면을 캡처합니다. 캡처에 민감한 정보가 보이지 않는지 확인합니다.
  3. 창에 있는 Abort merge(병합 취소. Revert 중이었다면 되돌리기 취소) 버튼을 누릅니다. 충돌이 나기 직전 상태로 돌아가고, 내가 커밋해 둔 내용은 그대로 남습니다. 버튼을 찾지 못하겠으면 누르지 말고 그대로 둡니다.
  4. 팀장에게 메신저로 알립니다. 저장소 이름, 브랜치, 무엇을 하다가 떴는지(Pull / Revert), 캡처를 보냅니다.
  5. 팀장이 해결하고 알려 주면, 평소의 공통 순서(저장소 확인 → 브랜치 선택 → Fetch origin → Pull origin)로 다시 시작합니다.

Continue merge, 파일별 선택 메뉴("이쪽 파일 사용")는 누르지 않습니다. 한쪽을 고르면 다른 쪽의 변경이 사라지는데, 어느 쪽을 살려야 하는지는 양쪽 변경을 모두 아는 사람이 정해야 합니다.

PR 화면의 충돌 안내

PR 화면 아래쪽에 "This branch has conflicts that must be resolved" 같은 안내와 Resolve conflicts 버튼이 보일 수 있습니다.

  • 버튼을 누르지 않습니다. 내 PC에서 할 일도 없습니다.
  • PR 주소와 함께 팀장에게 메신저로 알립니다. 팀장이 정리한 뒤 알려 주면 평소 순서대로 다시 시작합니다.
  • 여러분의 실수가 아닙니다. 같은 main 에 다른 변경이 먼저 들어가 같은 곳이 겹쳤다는 뜻입니다.

파일 안의 충돌 표시

충돌이 난 파일을 열면 Git이 양쪽 내용을 나란히 적어 둔 표시가 들어 있습니다.

<<<<<<< HEAD
제목: 주간 보고서
=======
제목: 월간 업무 보고
>>>>>>> origin/work

<<<<<<< 와 ======= 사이가 한쪽, ======= 와 >>>>>>> 사이가 다른 쪽입니다. 이 표시가 들어 있는 채로 커밋하지 않습니다. 도구가 실행되지 않습니다. AI에게 "이 표시를 지워 줘"라고 시키지도 않습니다. 표시만 지우면 어느 쪽을 살릴지 아무도 판단하지 않은 채로 합쳐집니다.

AI 활용 범위

무슨 일이 일어났는지 설명만 시키는 것은 괜찮습니다. 팀장에게 알릴 때 도움이 됩니다.

지금 충돌이 난 파일이 무엇인지, 양쪽이 각각 무엇을 바꾸려 했는지 쉬운 말로 설명해 줘. 아무것도 수정하거나 해결하지는 마.

4. 충돌 예방 습관

  1. 작업을 시작할 때 Fetch origin → Pull origin (공통 순서). Changes가 비어 있을 때 받습니다.
  2. 하루를 마칠 때 커밋하고 푸시합니다. 푸시하지 않은 커밋이 오래 쌓일수록 충돌 가능성이 커집니다.
  3. 팀장이 "work 에 수정을 넣었습니다"라고 알리면, 하던 것을 커밋·푸시한 뒤 바로 Pull 합니다.
  4. PR이 열려 있는 동안 관련 없는 새 작업을 하지 않습니다.
  5. 한 PC에서만 작업합니다. 두 PC에서 같은 저장소를 번갈아 고치면 혼자서도 충돌이 납니다.

5. 확인 문제

① PR을 만들었습니다. 이제 main에 반영된 건가요? 아니요. PR은 "반영해 달라는 요청"입니다. 팀장이 검토·승인한 뒤 병합해야 main 에 반영됩니다.
② 첫 PR이 병합됐습니다. 다음 작업 전에 work를 main에 맞춰야 하나요? 필요 없습니다. main 은 PR 병합으로만 바뀌고, 그 내용은 모두 내 work 에서 간 것입니다. 같은 work 에서 평소 순서대로 시작하면 됩니다.
③ 두 변경이 서로 다른 파일을 고쳤습니다. 합칠 때 충돌이 날까요? 나지 않습니다. Git이 자동으로 합칩니다. 같은 파일의 같은 곳을 다르게 고쳤을 때만 충돌이 납니다.
④ Pull을 눌렀더니 충돌 창이 떴습니다. 무엇을 하나요? 멈추고, 캡처하고, Abort merge 를 눌러 직전 상태로 돌아간 뒤, 팀장에게 메신저로 알립니다. Continue merge나 파일 선택 메뉴는 누르지 않습니다.
⑤ AI가 "새 브랜치를 만들어 작업할까요?"라고 묻습니다. 왜 묻는 걸까요, 어떻게 답하나요? 개발자들이 기능마다 브랜치를 새로 따는 관행 때문입니다. 우리 TF는 work 하나를 계속 쓰므로 "지금 브랜치에서 계속해 줘"라고 답합니다.

이어서 읽기

© KYONGHO ENGINEERING & ARCHITECTS