Git “fatal: index file corrupt” 해결 방법

Git “fatal: index file corrupt”란?

fatal: index file corrupt 오류는 Git의 핵심 파일 중 하나인 인덱스(index) 파일이 손상되었음을 의미합니다. 인덱스 파일(.git/index)은 “스테이징 영역(Staging Area)”이라고도 불리며, 다음 커밋에 포함될 변경 사항들의 목록을 추적하는 중요한 파일입니다. 이 파일이 손상되면 Git은 어떤 파일이 추적되고 있는지, 어떤 내용이 스테이징되었는지 알 수 없게 되어 대부분의 Git 명령이 실패하게 됩니다.

오류의 일반적인 원인

object file is empty 오류와 유사하게, 인덱스 파일 손상은 주로 다음과 같은 상황에서 발생합니다:

1. 비정상적인 종료: Git 명령(특히 git add, git reset, git commit 등 인덱스를 수정하는 명령) 실행 중에 컴퓨터가 갑자기 꺼지는 경우.
2. 파일 시스템 오류: 디스크 자체의 문제로 파일 내용이 깨지는 경우.
3. 외부 프로그램의 간섭: 파일 동기화 프로그램이나 일부 백신 프로그램이 .git/index 파일을 잘못 건드리는 경우.
4. 동시에 여러 Git 프로세스 실행: 하나의 저장소에서 동시에 여러 Git 명령이 인덱스 파일을 수정하려고 할 때 충돌이 발생하여 손상될 수 있습니다.

오류 해결 방법

경고: .git 디렉터리를 직접 조작하기 전에, 만일을 대비해 저장소 전체를 백업하는 것이 좋습니다.

인덱스 파일은 Git 저장소의 다른 객체들과 달리, 문제가 생겼을 때 비교적 안전하게 재생성할 수 있습니다. 인덱스는 기본적으로 현재 브랜치의 HEAD 커밋 상태와 워킹 디렉터리의 상태를 기반으로 다시 만들어질 수 있습니다.

방법 1: 인덱스 파일 삭제 후 리셋

가장 일반적이고 효과적인 해결 방법은 손상된 인덱스 파일을 삭제하고 Git이 새로 생성하도록 하는 것입니다.

1. .git/index 파일 삭제: 저장소의 루트 디렉터리에서 다음 명령을 실행하여 인덱스 파일을 제거합니다.

   # Linux/macOS
   rm .git/index
   
   # Windows
   del .git\index
   

   이 작업을 수행하면 스테이징했던 모든 변경 사항이 사라집니다 (커밋되지 않은 변경 사항은 워킹 디렉터리에 그대로 남아있습니다).

2. Git 상태 리셋: git reset 명령을 실행하여 HEAD 커밋 기준으로 인덱스를 새로 생성합니다. 이 명령은 워킹 디렉터리의 파일들은 건드리지 않습니다.

   git reset
   

   이제 git status 명령을 실행하면, 마지막 커밋 이후 변경된 모든 파일들이 “Changes not staged for commit” (스테이징되지 않은 변경 사항) 목록에 나타날 것입니다.

3. 변경 사항 다시 스테이징: 필요한 변경 사항들을 다시 git add 명령으로 스테이징합니다.

   git add <file1> <file2> ...
   # 또는 모든 변경 사항을 스테이징
   git add .
   

방법 2: 로컬 저장소를 새로 복제 (Clone)

만약 위 방법으로 해결되지 않거나, 로컬에 중요한 커밋되지 않은 변경 사항이 없다면 원격 저장소에서 새로 복제하는 것이 가장 깔끔한 해결책입니다.

1. 현재 로컬 저장소 폴더의 이름을 바꾸거나 삭제합니다.

   cd ..
   mv your-repo-name your-repo-name-backup
   

2. 원격 저장소에서 다시 복제합니다.

   git clone <your-remote-repository-url>
   

예방 조치

• Git 명령 실행 중에는 컴퓨터를 강제로 종료하지 않도록 주의합니다.
• .git 디렉터리는 파일 동기화 대상에서 제외하는 것이 안전합니다.
• 중요한 변경 사항은 작업 후 바로 커밋하고 원격 저장소에 푸시하는 습관을 들입니다.

결론

fatal: index file corrupt 오류는 당황스러울 수 있지만, 다행히 인덱스 파일은 Git 저장소의 핵심 데이터(객체)와는 분리되어 있어 상대적으로 쉽게 복구할 수 있습니다. 손상된 인덱스 파일을 삭제하고 git reset을 통해 새로 생성하는 방법으로 대부분의 문제를 해결할 수 있습니다. 이 과정에서 스테이징했던 내용은 사라지지만, 워킹 디렉터리의 실제 파일 변경 내용은 보존되므로 안전합니다.

전문 보완 체크

Git “fatal: index file corrupt” 해결 방법에서 중요한 기준은 독자가 한 번 따라 해서 성공했는지가 아닙니다. 이 주제는 재현 가능한 디버깅 절차로 다루는 편이 안전합니다. 결론을 내리기 전에 실행 환경, 정확한 오류 경계, 최소 재현 예제, 되돌릴 수 있는 경로를 확인해야 합니다. 또한 나중에 같은 문제가 반복될 수 있으므로, 관찰한 사실과 사용한 가정, 결론이 바뀔 조건을 짧은 결정 기록으로 남기는 것이 좋습니다.

신뢰도를 높이는 증거

작업을 바꾸기 전에는 객관적인 증거를 먼저 확인해야 합니다. 쓸 만한 증거에는 전체 명령 출력, 버전 번호, 변경된 파일, 기대 동작과 실제 동작가 포함됩니다. 증거가 서로 맞지 않으면 억지로 하나의 이야기로 합치지 말고 충돌 자체를 남겨야 합니다. 빠른 해결이 한 번 성공했더라도 같은 입력, 계정, 의존성, 기기 상태에서 다시 확인하지 않았다면 아직 확정된 해결책이라고 보기 어렵습니다.

검토 표

검토 항목	확인할 내용	중요한 이유
범위	이 글이 다루는 정확한 사례	조언을 과도하게 적용하지 않게 합니다
기준 상태	변경 전 상태	되돌리기와 비교를 가능하게 합니다
변경	실제로 수행한 가장 작은 조치	숨은 부작용을 줄입니다
결과	변경 뒤 관찰한 출력 또는 반응	기대와 증거를 구분합니다
재확인	결론을 다시 볼 시점	글의 정확도를 유지합니다

예외 상황과 실패 모드

주요 위험은 증상만 고치고 원인을 남기는 상황, 서로 무관한 변경을 같은 테스트에 섞는 상황입니다. 생산 데이터, 개인정보, 돈, 건강, 법적 권리, 보안 복구가 관련되어 있다면 넓은 해결책을 바로 적용하기보다 먼저 증거를 모으는 보수적인 접근이 낫습니다. 같은 제목의 문제라도 환경이 다르면 원인이 달라질 수 있으므로, 독자는 명령이나 결정을 복사하기 전에 자신의 조건이 글의 가정과 맞는지 비교해야 합니다.

유지보수 기준

이 안내는 의존성, 운영체제, 빌드 도구가 바뀐 뒤 다시 확인해야 합니다. 좋은 업데이트는 글 전체를 다시 쓰는 것이 아니라 예시, 링크, 명령, 화면, 판단 기준이 현재 동작과 여전히 맞는지 확인하는 일입니다. 기존 결론이 유효하면 확인 날짜를 남기고, 바뀌었다면 무엇이 바뀌었고 왜 이전 조언만으로 부족한지 설명해야 합니다.

실행 전 질문

• 문제나 판단이 실제임을 보여 주는 가장 작은 관찰 신호는 무엇인가?
• 공식 출처는 무엇이고, 내부 판단은 어느 부분인가?
• 변경 전에 반드시 캡처해야 할 기록은 무엇인가?
• 어떤 결과가 나오면 이 글의 조언이 맞지 않는다고 볼 것인가?
• 같은 문제가 반복될 때 누가 이 기록을 다시 봐야 하는가?

함께 보면 좋은 글

같은 주제 흐름에서 이어서 읽기 좋은 글입니다.

• SSL: CERTIFICATE_VERIFY_FAILED 오류 해결 방법 (Windows Python)
• Permission denied (publickey) 오류 해결 방법 (Windows Git SSH)