이미 커밋된 파일을 Git 추적에서 제외하는 방법

Git의 설계 원칙상 .gitignore는 아직 Git에 등록되지 않은 '추적되지 않은 파일(Untracked files)'에 대해서만 무시 규칙을 적용합니다. 이미 git add 및 git commit을 통해 저장소에 반영된 파일은 Git 인덱스(스테이징 영역)에서 계속 추적(Tracked)됩니다.

따라서 나중에 .gitignore 파일에 경로를 추가하더라도 Git이 자동으로 추적을 멈추지 않습니다. 로컬 디스크의 실제 파일은 그대로 보존하면서 Git의 인덱스에서만 파일을 제거(추적 해제)해야 합니다.

git rm 명령어에 --cached 옵션을 사용하면 로컬 컴퓨터의 파일은 보존한 채 Git 인덱스에서만 안전하게 파일을 제거할 수 있습니다:

# 1. .gitignore 파일에 해당 파일이 포함되어 있는지 확인
echo ".env" >> .gitignore

# 2. Git 인덱스에서만 파일 제거 (로컬 파일은 보존)
git rm --cached .env

# 3. 변경 사항 커밋
git commit -m "Stop tracking .env file"

build/ 또는 node_modules/ 폴더 전체가 실수로 커밋된 경우에는 재귀 옵션인 -r 플래그를 --cached와 함께 전달합니다:

# 1. .gitignore에 디렉터리 패턴 추가
echo "build/" >> .gitignore

# 2. 디렉터리를 재귀적으로 Git 인덱스에서 제거
git rm -r --cached build/

# 3. 제외 사항 커밋
git commit -m "Stop tracking build/ output directory"

.gitignore를 나중에 작성하여 이미 많은 파일이 커밋된 상태라면, 전체 인덱스 캐시를 한 번 비운 뒤 .gitignore 규칙에 따라 다시 추가하는 것이 가장 확실합니다:

# 1. 현재 작업 내용이 커밋되었거나 스태시되었는지 확인
git status

# 2. Git 인덱스의 모든 파일 캐시 제거
git rm -r --cached .

# 3. .gitignore 규칙을 준수하여 다시 추가
git add .

# 4. 캐시 갱신 커밋
git commit -m "Refresh repository tracking to match .gitignore"

환경 변수나 설정 파일을 추적 제외할 때는 미리 팀원들에게 공지하고, 대체용 템플릿인 .env.example 파일을 프로젝트에 제공하세요.