Git 'Conflicted Index' 에러, 한 방에 해결하기!

Git 'Conflicted Index' 에러, 개발자라면 한 번쯤 겪어보셨을 텐데요. 예상치 못한 코드 충돌은 작업 흐름을 방해하고, 때로는 해결책을 찾느라 귀중한 시간을 허비하게 만들기도 합니다.

이 글은 이 골치 아픈 에러의 원인을 깊이 파고들어, 깔끔하게 해결하는 실용적인 가이드를 제공합니다. Git의 핵심 개념인 인덱스를 이해하고, 어떤 상황에서 이 에러가 발생하는지, 그리고 효과적인 해결 전략까지 모두 알려드릴게요. 작업의 생산성을 높이고 싶은 모든 개발자분들께 이 글이 명쾌한 해결책이 될 것이라고 확신합니다.

Git의 세계에서 'Conflicted Index' 에러는 마치 교통 체증과 같습니다. 여러 갈래의 길이 한 지점에서 만나면서 어떤 길로 가야 할지 Git이 결정하지 못하고 멈춰 서는 상황인 것이죠. 이 에러를 정확히 이해하려면 먼저 Git의 '인덱스(Index)' 또는 '스테이징 영역(Staging Area)' 개념을 알아야 합니다.




● **Git 인덱스(Staging Area)란 무엇인가요?**

Git 인덱스는 작업 디렉토리(Working Directory)와 실제 저장소(Repository) 사이에 존재하는 중간 단계입니다. 개발자가 `git add` 명령어를 사용하면 변경된 파일이 이 인덱스에 추가되며, `git commit` 명령어를 실행하면 인덱스에 있는 파일들이 저장소에 최종적으로 기록되는 구조입니다.

즉, 인덱스는 다음 커밋에 포함될 변경 사항들을 미리 모아두는 '준비 공간' 역할을 해요. 'Conflicted Index' 에러는 바로 이 준비 공간에서 문제가 발생했을 때 나타나는 메시지입니다. 서로 다른 변경 사항이 같은 파일의 같은 위치를 건드렸을 때, Git이 어느 변경 사항을 선택해야 할지 몰라 충돌이 발생하고 인덱스가 '충돌 상태'가 되는 것이죠.




● **'Conflicted Index' 에러가 발생하는 주요 원인**

이 에러는 주로 다음과 같은 상황에서 발생합니다.




1. **병합(Merge) 충돌**: 가장 흔한 원인입니다. 두 개 이상의 브랜치가 같은 파일의 동일한 부분을 동시에 수정하고, 이 브랜치들을 병합하려 할 때 발생해요. Git이 어떤 수정 사항을 취해야 할지 자동으로 판단할 수 없게 됩니다.




2. **리베이스(Rebase) 충돌**: 브랜치의 커밋 내역을 다른 브랜치 위로 재배치하는 리베이스 과정에서 충돌이 발생할 수 있습니다. 각 커밋이 순차적으로 적용될 때마다 충돌을 해결해야 할 수도 있어요.




3. **충돌 해결 중 작업 중단**: 충돌이 발생한 후 파일을 수동으로 수정하다가 `git add`나 `git commit`을 완료하지 않은 상태에서 다른 작업을 시도하거나, 터미널을 닫아버리는 경우에도 인덱스가 충돌 상태로 남을 수 있습니다.




4. **`git reset` 등의 명령어 오용**: 특정 시점으로 되돌리거나 인덱스를 조작하는 명령어들을 잘못 사용했을 때, 예기치 않은 충돌 상태가 발생할 수 있습니다.




● **깔끔한 'Conflicted Index' 에러 해결 가이드**

이제 실전으로 들어가 에러를 해결하는 방법을 알아볼게요. 예를 들어, `main` 브랜치에 있는 `README.md` 파일을 `feature` 브랜치에서 수정했고, 동시에 다른 동료가 `main` 브랜치에서도 `README.md` 파일을 수정하여 `main` 브랜치에 푸시한 상황이라고 가정해 봅시다. 이제 `feature` 브랜치를 `main` 브랜치에 병합하려고 할 때 충돌이 발생할 수 있습니다.

**


1. 충돌 상태 확인**:

가장 먼저 `git status` 명령어를 실행하여 현재 Git 저장소의 상태를 확인해야 합니다.

```bash
git status
```

결과로 `Changes to be committed:` 섹션과 `Unmerged paths:` 섹션이 나타날 것입니다. `Unmerged paths:` 아래에 충돌이 발생한 파일 목록이 표시됩니다.

**


2. 충돌 파일 식별 및 내용 확인**:

`git status`에서 확인된 충돌 파일을 텍스트 에디터로 엽니다. 충돌이 발생한 부분에는 다음과 같은 Git 충돌 마커가 추가되어 있습니다.

```
<<<<<<< HEAD
여기는 현재 브랜치(HEAD)의 내용입니다.
=======
여기는 병합하려는 브랜치의 내용입니다.
>>>>>>> feature/branch-name
```

* `<<<<<<< HEAD`: 현재 브랜치(HEAD)의 변경 사항 시작
* `=======`: 두 변경 사항의 구분선
* `>>>>>>> feature/branch-name`: 병합하려는 브랜치의 변경 사항 끝

**


3. 충돌 수동 해결**:

Git 충돌 마커(`<<<<<<<`, `=======`, `>>>>>>>`)를 제거하고, 두 브랜치의 변경 사항 중 최종적으로 반영하고 싶은 내용을 직접 선택하거나, 새로운 내용으로 수정하여 파일을 완성합니다. 이 과정이 가장 중요하며, 코드를 신중하게 검토해야 합니다.

예를 들어, 두 브랜치에서 모두 필요한 내용이라면 다음과 같이 수정할 수 있습니다.

```
여기는 현재 브랜치와 병합하려는 브랜치의 내용을 합친 결과입니다.
```

**


4. 해결된 파일 스테이징**:

충돌을 해결한 후, 수정된 파일을 Git 인덱스에 추가합니다.

```bash
git add <충돌 파일 이름>
```

충돌 파일이 여러 개라면 각 파일에 대해 이 명령어를 반복하거나, `git add .` 명령어를 사용하여 현재 디렉토리의 모든 변경 사항을 스테이징할 수 있습니다. 하지만 `git add .`는 의도치 않은 파일을 추가할 수도 있으므로, 충돌 파일이 많지 않다면 개별적으로 추가하는 것을 권장합니다.

**


5. 병합/리베이스 완료**:

모든 충돌 파일을 스테이징했다면, 병합 또는 리베이스 작업을 계속 진행합니다.

* **병합(Merge) 중이었다면**:

```bash
git commit
```
이 명령어를 실행하면 충돌 해결 커밋 메시지가 자동으로 생성되며, 메시지를 확인하고 저장하면 병합이 완료됩니다.

* **리베이스(Rebase) 중이었다면**:

```bash
git rebase --continue
```
리베이스는 각 커밋마다 충돌이 발생할 수 있으므로, 모든 충돌이 해결될 때까지 `git rebase --continue`를 반복해야 합니다.

**


6. 작업 취소 (선택 사항)**:

만약 충돌 해결이 너무 복잡하거나, 아예 처음부터 다시 시작하고 싶다면 작업을 취소할 수 있습니다.

* **병합(Merge) 중이었다면**:

```bash
git merge --abort
```
이 명령어는 병합을 취소하고 병합 시도 전 상태로 되돌립니다.

* **리베이스(Rebase) 중이었다면**:

```bash
git rebase --abort
```
이 명령어는 리베이스를 취소하고 리베이스 시도 전 상태로 되돌립니다.

충돌 해결 명령어들을 한눈에 비교해볼까요?

상황	Git 명령어	설명
현재 저장소 상태 확인	git status	충돌 파일 및 인덱스 상태를 파악합니다.
충돌 파일 스테이징	git add <파일 경로>	수동으로 충돌을 해결한 파일을 인덱스에 추가합니다.
병합(Merge) 완료	git commit	충돌 해결 후 병합 커밋을 생성하여 작업을 마무리합니다.
리베이스(Rebase) 완료	git rebase --continue	현재 단계의 충돌 해결 후 리베이스를 다음 커밋으로 진행합니다.
병합(Merge) 취소	git merge --abort	병합을 취소하고 원래 브랜치 상태로 되돌립니다.
리베이스(Rebase) 취소	git rebase --abort	리베이스를 취소하고 리베이스 시작 전 상태로 되돌립니다.

 

Git 'Conflicted Index' 에러는 Git 인덱스와 충돌 발생 메커니즘을 이해하면 충분히 관리할 수 있는 문제입니다. 이 가이드가 여러분의 Git 트러블슈팅에 큰 도움이 되기를 바랍니다.

마지막으로 한 가지 팁을 드리자면, 항상 작업을 시작하기 전에 최신 변경 사항을 `git pull` 받아 로컬 저장소를 최신 상태로 유지하는 습관을 들이세요. 이는 충돌 발생 가능성을 현저히 줄여주며, 발생하더라도 더 작은 범위의 충돌로 관리하기 쉽게 만들어 줄 것입니다. 꾸준한 학습과 실습을 통해 Git 숙련도를 높여 효율적인 개발 환경을 구축하시길 응원합니다!