Git 충돌 해결: 'conflicted index' 완벽 가이드

Git과 씨름하다 갑자기 'Automatic merge failed; fix conflicts and then commit the result.' 또는 'conflicted index' 메시지를 마주하고 당황했던 경험, 혹시 없으신가요? 이는 Git을 사용하는 개발자라면 누구나 한 번쯤 겪게 되는 흔한 상황입니다.

이 글에서는 `conflicted index` 에러의 원인과 발생 시 효과적으로 대처하는 방법을 상세히 다룹니다. Git 병합 전략부터 실제 해결 과정까지, 복잡한 충돌 문제를 쉽고 완벽하게 해결하는 노하우를 얻어가실 수 있을 거예요.

Git 충돌(Conflict)은 여러 개발자가 같은 코드베이스에서 작업할 때 필연적으로 발생합니다. 특히 'conflicted index' 에러는 Git이 자동으로 변경 사항을 병합할 수 없어, 수동 개입이 필요한 상태임을 알려주는 신호죠. 이 에러는 주로 다음과 같은 상황에서 발생합니다.




● **동일한 파일의 동일한 라인을 동시에 수정했을 때**
가장 흔한 충돌 유형입니다. 예를 들어, `main` 브랜치에서 `feature/login` 브랜치를 따서 작업하던 A 개발자와, `feature/logout` 브랜치를 따서 작업하던 B 개발자가 우연히 같은 설정 파일의 특정 라인을 각자의 방식으로 수정했을 때 발생할 수 있습니다.




● **파일 삭제와 수정이 동시에 이루어졌을 때**
한 브랜치에서 특정 파일을 수정했는데, 다른 브랜치에서는 그 파일을 삭제해버린 경우에도 충돌이 발생합니다. Git은 어떤 변경이 우선되어야 할지 판단하기 어렵기 때문이죠.




● **브랜치 병합(Merge) 또는 리베이스(Rebase) 과정**
가장 핵심적인 발생 지점입니다. 특정 브랜치의 변경사항을 다른 브랜치로 합치는 과정에서, Git이 두 브랜치의 변경 이력을 비교하다가 모순을 발견하면 충돌이 발생합니다.

**`conflicted index` 에러란 무엇인가요?**

`conflicted index` 에러는 Git이 'Index'(스테이징 영역)에 충돌이 발생한 파일이 있음을 감지했음을 의미합니다. 즉, Git은 현재 어떤 변경 사항을 최종으로 확정해야 할지 알 수 없는 상태이고, 개발자가 직접 충돌을 해결하여 스테이징 영역에 추가해줘야 한다는 뜻이죠. `git status` 명령어를 입력했을 때, `both modified:` 또는 `deleted by us:`, `added by them:` 등의 메시지가 나타나며 충돌 파일을 알려줄 것입니다.

**Git 충돌 해결, 단계별 가이드**

Git 충돌 해결은 몇 가지 단계를 거쳐 진행됩니다. 침착하게 다음 단계를 따라오시면 어떤 충돌도 해결할 수 있습니다.




1. **충돌 상태 확인: `git status`**

가장 먼저 해야 할 일은 어떤 파일이 충돌 상태인지 확인하는 것입니다. `git status` 명령어를 실행하면 충돌이 발생한 파일 목록과 함께 `Unmerged paths` 섹션이 표시됩니다.

```bash
$ git status
On branch main
You have unmerged paths.
(fix conflicts and run "git commit")
(use "git merge --abort" to abort the merge)

Unmerged paths:
(use "git add ..." to mark resolution)

both modified: src/config.js

no changes added to commit (use "git add" and/or "git commit -a")
```

위 예시에서는 `src/config.js` 파일에서 충돌이 발생했음을 알 수 있습니다.





2. **충돌 파일 열기 및 내용 수동 편집**

충돌이 발생한 파일을 텍스트 에디터나 IDE(VS Code, IntelliJ 등)로 엽니다. 파일 내부에 Git이 삽입한 충돌 마커를 확인할 수 있습니다.

```javascript
<<<<<<< HEAD
const API_URL = "https://api.example.com/v1"; // 나의 작업 (HEAD)
=======
const API_URL = "https://newapi.example.com/v2"; // 병합하려는 브랜치 (상대방 작업)
>>>>>>> feature/new-api
```

* `<<<<<<< HEAD`: 현재 작업하고 있는 브랜치의 변경 내용 시작. (나의 변경)
* `=======`: 두 변경 내용의 구분선.
* `>>>>>>> [브랜치 이름 또는 커밋 해시]`: 병합하려는 브랜치의 변경 내용 끝. (상대방의 변경)

개발자는 이 마커들을 제거하고, 원하는 최종 코드를 직접 작성해야 합니다.

```javascript
const API_URL = "https://api.example.com/v2"; // 최종 결정된 코드
```

이처럼 양쪽의 변경 내용을 모두 반영하거나, 한쪽의 변경 내용만 선택하거나, 완전히 새로운 내용으로 수정할 수 있습니다.





3. **충돌 해결 완료 알림: `git add `**

충돌 파일을 수동으로 편집하여 원하는 상태로 만든 후에는, Git에게 이 파일의 충돌이 해결되었음을 알려야 합니다.

```bash
$ git add src/config.js
```

`git status`를 다시 실행하면, 해당 파일이 `Changes to be committed` 섹션으로 이동한 것을 볼 수 있습니다. 이는 충돌이 해결되었고, 이제 커밋할 준비가 되었다는 의미입니다.





4. **병합 커밋: `git commit`**

모든 충돌 파일을 `git add`로 스테이징 영역에 추가했다면, 마지막으로 병합 커밋을 생성해야 합니다.

```bash
$ git commit
```

Git은 자동으로 병합 커밋 메시지를 생성해줍니다. 특별한 경우가 아니라면 기본 메시지를 그대로 사용해도 되지만, 충돌 해결에 대한 상세 내용을 추가하면 나중에 커밋 히스토리 추적에 도움이 됩니다.

```
Merge branch 'feature/new-api' into main

# Conflicts:
# src/config.js
#
# It looks like you may be merging a branch whose tip is not a direct descendant of your current branch.
# As a result, you are merging to a commit that is not a direct ancestor of your current branch.
# If this is not what you intended, you may wish to use "git pull --rebase" instead.
#
# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
```

메시지 편집기를 닫으면 병합이 완료됩니다.

**💡 팁:** 만약 충돌 해결이 너무 복잡하여 처음부터 다시 시작하고 싶다면, `git merge --abort` (Merge 중인 경우) 또는 `git rebase --abort` (Rebase 중인 경우) 명령어를 사용하여 병합/리베이스 작업을 중단하고 이전 상태로 되돌릴 수 있습니다.

**Git 병합(Merge) 전략과 충돌 관리 팁**

Git에서 브랜치를 합치는 방법은 크게 Merge와 Rebase 두 가지가 있습니다. 각각의 특징을 이해하고 상황에 맞게 사용하는 것이 중요합니다.

특징	Merge	Rebase
**히스토리**	병합 커밋 생성, 브랜치 히스토리 보존 (그래프 형태)	병합 커밋 없이 깔끔한 선형 히스토리 생성 (히스토리 변경)
**충돌 처리**	병합 과정 중 한 번에 충돌 처리	각 커밋마다 충돌이 발생할 수 있어 여러 번 처리해야 할 수도 있음
**안정성**	히스토리가 변경되지 않아 안전	이미 푸시된 브랜치에 사용 시 히스토리 변경으로 팀원들과 문제 발생 가능성 (공유 브랜치에선 지양)
**권장 용도**	메인 브랜치로 기능 브랜치 병합 시, 공유 브랜치	개인 작업 브랜치를 최신 상태로 유지할 때, 깨끗한 히스토리 선호 시

**충돌 예방 및 관리 팁:**

* **작게, 자주 커밋하세요:** 변경 사항이 작을수록 충돌 발생 가능성이 줄고, 발생하더라도 해결하기 쉽습니다.
* **자주 최신 상태로 유지하세요:** `git pull`을 자주 사용하여 로컬 브랜치를 원격 저장소의 최신 상태로 유지하면, 큰 충돌을 미연에 방지할 수 있습니다.
* **작업 시작 전 `git pull`:** 새로운 작업을 시작하기 전에는 항상 현재 브랜치의 최신 변경 사항을 가져오는 습관을 들이세요.
* **Merge Tool 활용:** VS Code, IntelliJ, Sublime Merge, Meld 등 시각적인 Merge Tool을 사용하면 충돌 해결을 훨씬 직관적이고 빠르게 할 수 있습니다. `git mergetool` 명령어로 설정된 도구를 실행할 수 있습니다.

Git 충돌은 개발 협업 과정에서 피할 수 없는 부분이지만, `conflicted index` 에러를 포함한 다양한 충돌 상황을 올바르게 이해하고 단계별로 접근하면 충분히 해결할 수 있습니다.

충돌 해결 과정을 익숙하게 만들면 개발 생산성을 높이고 팀원과의 협업을 더욱 원활하게 할 수 있을 거예요. 모든 개발자분들이 Git 충돌의 공포에서 벗어나 자신감 있게 코딩하시길 응원합니다!