gitignore 적용 전 확인할 추적 상태와 예외 규칙

.gitignore에 파일 이름을 적었는데도 git status에 수정 사항이 계속 보일 수 있다. 이때 먼저 확인할 것은 규칙의 철자보다 파일이 이미 Git에 등록돼 있는지다. .gitignore는 아직 추적하지 않는 파일을 앞으로 무시하는 규칙이며, 이미 추적 중인 파일을 자동으로 빼주지는 않는다.

추적 중인 파일을 로컬에 남기면서 이후 커밋에서 제외하려면 해당 경로에 git rm --cached를 적용하고 .gitignore 변경과 함께 커밋한다. 저장소 전체를 한꺼번에 다시 등록하기보다 문제 파일 하나의 상태를 확인하는 편이 변경 범위를 파악하기 쉽다.

1. 파일이 이미 추적되고 있는가

아래 명령은 저장소 최상위 폴더에서 실행한다. 예시의 notes.local.txt는 개인 작업 메모 파일이며, 실제 프로젝트에서는 확인하려는 경로로 바꾼다.

git status --short
git ls-files --error-unmatch -- notes.local.txt
git check-ignore -v --no-index -- notes.local.txt

git ls-files가 파일 경로를 출력하고 성공하면 인덱스에 등록된 파일이다. git check-ignore -v --no-index는 추적 여부와 별개로 어떤 무시 규칙이 해당 경로와 일치하는지 확인한다. 출력에는 규칙 파일, 줄 번호, 패턴이 함께 나온다.

확인 결과	의미	다음 확인
추적 중이고 무시 규칙도 일치	규칙이 있어도 기존 추적은 유지됨	계속 버전 관리할 파일인지 판단
미추적이고 무시 규칙이 일치	일반적인 git add 대상에서 제외됨	필요한 파일까지 빠졌는지 확인
일치하는 무시 규칙이 없음	파일명·경로·규칙 위치가 원인일 수 있음	루트 기준 경로와 예외 패턴 점검

기본 git check-ignore는 추적 중인 파일을 검사 대상으로 보여주지 않는다. 출력이 없다는 이유만으로 규칙이 틀렸다고 판단하지 않고, 이 경우에만 --no-index를 붙여 규칙 자체를 점검한다.

2. 로컬 파일을 남기고 추적에서 제외하기

공유해야 하는 설정이나 소스 파일은 그대로 추적한다. 로컬 전용 파일로 정리하기로 했다면 .gitignore에 다음 규칙을 추가한다. 앞의 /는 이 .gitignore가 있는 폴더를 기준으로 경로를 제한한다.

/notes.local.txt

삭제 예정 대상을 먼저 보고, 그다음 정확한 한 경로만 인덱스에서 제거한다.

git rm -n --cached -- notes.local.txt
git rm --cached -- notes.local.txt
git add -- .gitignore
git diff --cached --name-status
git status --short --ignored

--cached가 있으므로 이 작업에서는 로컬 파일을 남긴다. staged diff에 표시되는 D는 다음 커밋의 파일 목록에서 빠진다는 뜻이다. 대상과 .gitignore 변경을 확인한 뒤 커밋한다.

git commit -m "Stop tracking local notes"

이후 git status --short --ignored에서 해당 파일은 !! notes.local.txt처럼 표시된다. 공유 저장소에 이 커밋을 전달하면 다른 작업자에게도 저장소상 삭제 변경이 전달되므로, 모두에게 필요한 파일을 개인 취향으로 제외하지 않는다. 로컬 설정이 필요한 프로젝트라면 비밀값이 없는 예제 설정을 별도로 공유할 수 있다.

3. 디렉터리 안의 파일 하나만 다시 포함하기

!로 시작하는 규칙은 앞선 무시 규칙을 되돌리는 예외다. 다만 상위 디렉터리 자체가 제외돼 있으면 그 안의 파일만 예외로 다시 포함할 수 없다.

다음처럼 디렉터리 전체를 제외하면 의도대로 동작하지 않는다.

cache/
!cache/.gitkeep

루트의 cache 폴더는 검사할 수 있게 두고 내부 항목을 제외하면 예외 파일을 발견할 수 있다.

/cache/*
!/cache/.gitkeep

여기서 .gitkeep은 Git의 특별한 기능이 아니다. 빈 디렉터리 대신 추적할 작은 파일에 붙이는 관례적인 이름이다. 하위 디렉터리 안의 파일을 포함하려면 그 상위 경로도 하나씩 제외되지 않도록 해야 한다.

같은 우선순위에서는 마지막으로 일치하는 규칙이 적용된다. 하위 폴더의 .gitignore도 영향을 줄 수 있으므로 최종 판단은 git check-ignore -v의 출력으로 확인한다. 예외 규칙에 일치한 경로를 명시적으로 검사하면 출력에 ! 패턴이 나올 수도 있으니, 출력 유무만 보지 않고 패턴까지 읽는다.

4. 새 저장소에서 확인한 동작

Git 2.55.0의 별도 실습 저장소에서 메모 파일을 먼저 커밋하고 위 과정을 실행했다.

단계	확인한 결과
추적 파일을 수정하고 .gitignore에 등록	여전히 수정 파일로 표시
git rm --cached 실행	로컬 파일은 남고 staged diff에는 삭제 표시
무시 규칙과 추적 제외를 커밋	파일은 추적 목록에서 사라지고 !!로 표시
cache/와 내부 파일 예외 사용	.gitkeep까지 제외됨
/cache/*와 예외 사용	.gitkeep은 미추적 파일로 발견되고 로그 파일은 제외됨

.gitignore와 git rm --cached는 과거 커밋에서 파일 내용을 지우는 작업이 아니다. 이미 공개한 비밀값을 처리해야 하는 경우에는 자격 증명 폐기·교체와 이력 정리를 별도로 검토해야 한다.

적용을 마친 뒤에는 추적 목록, 무시 규칙의 출처, staged diff 세 가지를 다시 확인한다. 이 셋이 맞으면 파일이 계속 보이는 이유와 다음 커밋에 포함되는 변경을 구분할 수 있다.