.gitignore에 추가했는데도 파일이 계속 변경 목록에 뜰 때: 캐시 삭제 방법

SmartInfoBank 운영자 · 작성 2026-10-26 · 수정 2026-10-26 · 6분

프로젝트를 진행하다가 특정 설정 파일이나 임시 파일을 저장소에서 제외하기 위해 .gitignore 파일에 해당 경로를 추가하는 경우가 많습니다. 하지만 .gitignore에 파일명을 등록하고 저장했는데도 git status를 입력하면 여전히 변경 사항(modified) 목록에 나타나 의아할 수 있습니다. 이는 Git의 무시 규칙이 작동하지 않는 것이 아니라, 해당 파일이 이미 Git의 추적 대상(인덱스)에 등록되어 있기 때문입니다.

.gitignore가 기존 파일을 자동으로 무시하지 못하는 원인

공식 문서 Git gitignore Documentation에 따르면, .gitignore 파일의 주 목적은 의도적으로 추적하지 않을 파일(untracked files)을 무시하는 것입니다. 따라서 이미 한 번이라도 커밋되었거나 인덱스(Staging Area)에 추가되어 추적되고 있는(tracked) 파일은 .gitignore에 규칙을 추가해도 영향을 받지 않습니다.

Git은 파일의 상태를 검사할 때 먼저 인덱스에 해당 경로가 존재하는지 확인합니다. 이미 인덱스에 올라간 파일은 작업 트리에서 수정될 때마다 추적 대상 변경 사항으로 분류되므로, .gitignore에 등록하기 전에 먼저 인덱스 목록에서 해당 파일의 추적을 해제해 주어야 합니다.

실제 재현 과정과 동작 확인

명령 프롬프트에서 'echo secret=123 > config.env'로 파일을 생성하고 'git add config.env' 및 커밋을 완료한 뒤, 뒤늦게 '.gitignore'에 'config.env'를 추가하고 'config.env' 내용을 수정하면 'git status'에 'modified: config.env'로 계속 감지됩니다. 이때 'git rm --cached config.env'를 실행하면 작업 디렉터리의 실제 config.env 파일은 삭제되지 않고 Git 인덱스에서만 제거되며, 이후 커밋을 완료하면 해당 파일이 더 이상 변경 추적 목록에 나타나지 않게 됩니다.

작업 트리 파일을 보존하며 인덱스만 정리하는 단계

공식 문서 Git git-rm Documentation에 명시되어 있듯이, git rm 명령어에 --cached 옵션을 지정하면 작업 트리(working tree)에 있는 실제 파일은 그대로 둔 채 Git 인덱스(index)에서만 해당 경로를 제거합니다. 로컬 파일을 지우지 않고 추적만 중단하는 안전한 절차는 다음과 같습니다.

1. 파일 수정 사항 및 상태 확인: git status 명령어로 추적을 중단할 대상 파일이 현재 변경 목록에 있는지 확인합니다.
2. .gitignore에 대상 파일 경로 등록: 무시할 파일 이름(예: config.env)을 .gitignore에 적고 저장합니다.
3. 인덱스에서 추적 해제: 터미널에서 git rm --cached 파일경로 명령을 실행합니다. 폴더 전체를 해제할 때는 -r 옵션을 함께 사용합니다.
4. 추적 해제 상태 스테이징 및 커밋: git status를 확인하면 대상 파일에 대해 deleted 상태가 인덱스에 기록되고, 작업 트리의 파일은 Untracked 목록에도 뜨지 않음을 확인한 뒤 git commit -m "추적 해제"로 커밋을 마칩니다.

이 과정을 거치면 로컬 작업 디렉터리에 실제 파일은 삭제되지 않고 안전하게 남아 있으며, 이후 파일 내용을 변경하더라도 Git 추적 대상에 잡히지 않습니다.

명령어 적용 시 주의점과 한계

git rm --cached 명령어를 적용할 때 확인해야 할 한계와 예외 동작이 있습니다.

• 단순 rm과의 차이: --cached 옵션을 빠뜨리고 git rm만 입력하면 로컬 작업 디렉터리의 실제 파일 자체가 지워집니다.
• 과거 커밋 기록 보존: 이 명령은 앞으로의 커밋부터 해당 파일의 변경 사항을 추적하지 않도록 인덱스에서 뺄 뿐, 과거에 이미 커밋된 이력 속 파일 내용(예: 이전에 커밋된 비밀번호나 API 키 등)까지 저장소 기록에서 지워 주지는 못합니다.
• 다른 저장소와의 동기화 시점: 이 변경 사항을 원격 저장소에 푸시한 후 다른 작업자가 변경 내역을 풀(pull)받을 때, 해당 커밋에 담긴 파일 삭제 기록으로 인해 협업자의 작업 트리에서 파일이 사라질 수 있으므로 공유 설정 파일의 경우 미리 별도 백업을 안내해야 합니다.