.gitignore에 넣어도 계속 추적될 때: git rm --cached로 추적만 중단하기

이미 Git이 추적하는 파일은 .gitignore에 적어도 무시되지 않습니다 (Git). 작업 파일을 남기고 추적만 멈추려면 git rm --cached로 인덱스에서 제거한 뒤 무시 규칙을 추가합니다 (Git). --cached를 쓰면 작업 트리의 파일은 그대로 남습니다 (Git).

To stop tracking a file that is currently tracked

시작 전 준비

설치된 Git 버전은 git --version으로 확인합니다 (Git).

• 이 절차는 이미 추적 중인 파일을 대상으로 합니다 (Git). 인덱스에 있는 파일은 추적 파일이며, git ls-files는 기본적으로 이 목록을 보여 줍니다 (Git). git-ls-files - Show information about files in the index and the working tree
• 아래 명령의 <경로>는 실제 대상 파일 경로로 바꿉니다 (Git). 파일을 지정하면 해당 파일만 확인할 수 있습니다 (Git).

git ls-files --error-unmatch <경로>

파일이 인덱스에 없으면 --error-unmatch는 오류로 처리하고 1을 반환합니다 (Git). 이미 추적하지 않는 파일이라면 이 글의 추적 해제 절차를 적용할 대상이 아닙니다 (Git, Git).

진행 순서

1. 제거할 대상을 미리 봅니다. -n은 실제로 제거하지 않고 대상만 보여 줍니다 (Git). --는 옵션과 파일 목록을 구분합니다 (Git). git-rm - Remove files from the working tree and from the index

git rm -n --cached -- <경로>

2. 인덱스에서만 제거합니다. --cached는 작업 트리 파일을 남기고 인덱스에서만 경로를 제거합니다 (Git). To stop tracking a file that is currently tracked

git rm --cached -- <경로>

3. 파일 이름을 .gitignore에 추가합니다. 공식 매뉴얼은 인덱스에서 제거한 뒤 무시 규칙을 추가하면 이후 커밋에 다시 들어가는 것을 막을 수 있다고 설명합니다 (Git).

4. 변경을 기록하려면 .gitignore 수정도 스테이징하고 커밋합니다. 수정한 파일은 git add로 최신 내용을 스테이징하며 (Pro Git), 커밋은 스테이징 영역의 스냅샷을 기록합니다 (Pro Git). git diff --cached로 스테이징된 내용을 확인할 수 있습니다 (Pro Git). 다음은 이 원칙을 적용한 예시 명령이며, -m은 커밋 메시지를 지정합니다 (Pro Git).

git add .gitignore
git diff --cached
git commit -m "Stop tracking local settings"

완료 확인

• 추적 목록에서 빠졌는지 확인합니다. 아래 명령에서 대상이 인덱스에 없다는 오류와 종료값 1이 나오면 추적 목록에서 빠진 상태입니다 (Git). git-ls-files - Show information about files in the index and the working tree

git ls-files --error-unmatch <경로>

• 작업 파일이 남아 있는지도 확인합니다. --cached로 제거한 파일은 수정 여부와 관계없이 작업 트리에 그대로 남아야 합니다 (Git).
• 무시 규칙도 남아 있어야 합니다. 인덱스 제거와 .gitignore 추가는 이후 커밋에 파일이 다시 들어가는 것을 막기 위한 서로 연결된 조치입니다 (Git).

한계와 주의

--cached를 사용할 때는 스테이징된 내용이 브랜치 끝 커밋이나 디스크의 파일 중 하나와 일치해야 합니다 (Git). 명령이 거부되면 상태를 먼저 확인하고, 이 글의 절차에 강제 제거 옵션을 임의로 덧붙이지 마세요.

이 글의 확인 대상은 현재 작업 트리와 인덱스입니다. 과거 커밋 속 비밀번호·토큰을 지우거나 유출된 키를 폐기하는 절차는 다루지 않습니다. 비밀 정보가 커밋되었다면 해당 서비스와 저장소 호스팅 서비스의 공식 안내를 별도로 확인해야 합니다.

이 글은 이미 추적 중인 파일을 다룹니다. 상위 디렉터리가 무시된 파일을 다시 포함시키는 문제는 별도이며, 공식 매뉴얼은 상위 디렉터리가 제외되면 그 안의 파일을 다시 포함할 수 없다고 설명합니다 (Git). 명령이 거부되면 git-rm 공식 매뉴얼의 조건을 대조하세요. git-rm - Remove files from the working tree and from the index

문서 기준: gitignore·git-ls-files는 2.55.0, git-rm은 2.50.0을 마지막 변경 버전으로 표시합니다 (Git, Git, Git).