Git .gitignore가 적용되지 않을 때는 파일의 추적 상태부터 확인해야 한다. 이미 커밋한 파일에 무시 규칙을 추가해도 변경 사항이 계속 표시되는 것은 정상 동작이다. 반면 아직 추적하지 않는 파일이 계속 나타난다면 패턴의 위치, 적용 순서, 예외 규칙을 살펴봐야 한다.
해결 순서는 간단하다. git ls-files로 추적 여부를 확인하고, git check-ignore -v --no-index로 규칙을 검증한 다음, 필요한 경로에만 git rm --cached를 적용한다. 아래 절차는 2026년 기준으로 확인할 핵심 동작을 Git 공식 문서의 규칙에 맞춰 정리한 것이다.
📌 핵심 요약
.gitignore는 추적하지 않는 파일에 적용되며, 이미 추적 중인 파일의 변경을 숨기지 않는다.- 추적 상태와 무시 규칙은 별도로 진단한다. 규칙이 맞아도 추적 중이면 변경 사항에 표시될 수 있다.
git rm --cached는 로컬 파일을 남기고 인덱스에서 제거한다. 다음 커밋에는 저장소에서의 삭제가 반영되며, 과거 커밋은 그대로 남는다.
1. git ls-files로 이미 추적 중인 파일인지 확인하기
.gitignore는 Git이 아직 추적하지 않는 파일을 의도적으로 제외하는 규칙 파일이다. Git 공식 gitignore 문서는 이미 추적 중인 파일에는 영향을 주지 않는다고 명시한다. 따라서 무시 규칙을 추가하는 것과 기존 추적을 해제하는 것은 서로 다른 작업이다.
명령 예시는 저장소 최상위 디렉터리에서 실행하는 것으로 가정한다. 먼저 문제가 되는 파일 하나를 지정해 인덱스에 등록되어 있는지 확인한다. 인덱스는 다음 커밋에 들어갈 파일 상태를 관리하는 영역이다.
git ls-files -- .env결과에 .env가 나오면 현재 인덱스에서 추적 중이다. 이미 커밋된 파일뿐 아니라 git add로 새로 등록한 파일도 여기에 포함된다. 아무것도 나오지 않으면 지정한 경로가 맞는지 확인한 뒤 무시 패턴 진단으로 넘어간다.
이 단계에서는 파일 내용이나 환경 변수 값을 출력할 필요가 없다. 경로만 확인해도 원인을 충분히 좁힐 수 있다. 특히 비밀값이 담긴 파일은 문제를 설명하려고 내용을 로그나 협업 도구에 붙여 넣지 않는 편이 좋다.
1. git ls-files로 이미 추적 중인 파일인지 확인하기
2. git check-ignore -v --no-index로 적용된 규칙 찾기
추적 여부를 확인했다면 같은 경로에 어떤 무시 규칙이 적용되는지 검사한다. -v는 규칙의 출처 파일, 줄 번호, 패턴, 대상 경로를 보여준다. --no-index는 인덱스 확인을 생략하므로 이미 추적 중인 파일의 규칙도 진단할 수 있다.
git check-ignore -v --no-index -- .env예를 들어 최상위 .gitignore의 3번째 줄에 /.env를 작성했다면 다음과 같은 형태가 나올 수 있다. 아래 결과는 출력 형식을 설명하기 위한 예시이며, 실제 줄 번호와 패턴은 저장소마다 다르다.
.gitignore:3:/.env .env이 결과는 해당 경로에 무시 패턴이 일치한다는 뜻이다. 다만 --no-index를 사용했으므로 현재 추적이 해제됐다는 의미는 아니다. 앞 단계에서 추적 중으로 확인됐다면 규칙을 고치는 대신 추적 해제가 필요한지 판단해야 한다.
기본 명령인 git check-ignore -v -- .env는 추적 중인 파일을 표시하지 않는다. 따라서 출력이 없다는 이유만으로 패턴이 잘못됐다고 단정하면 진단이 꼬일 수 있다. 또한 상세 출력에 !로 시작하는 패턴이 보이면 무시를 취소하는 예외에 일치한 것인지 확인해야 한다.
Git 공식 git-check-ignore 문서의 종료 코드도 자동화에서 유용하다. 기본적인 검사에서 무시되는 경로가 있으면 0, 없으면 1, 치명적 오류는 128이다. 경로가 무시되지 않아 반환된 1을 명령 실행 자체의 장애와 혼동하지 않는 것이 중요하다.
2. git check-ignore -v --no-index로 적용… 바로가기
3. git rm --cached로 필요한 파일만 추적 해제하기
계속 로컬에서 사용하되 저장소에는 넣지 않을 파일이라면, 먼저 .gitignore에 규칙을 저장한다. 저장소 최상위의 .env만 제외하려는 경우에는 다음처럼 작성한다. 하위 디렉터리의 같은 이름까지 제외할 것인지에 따라 패턴은 달라져야 한다.
# .gitignore
/.env그다음 해당 파일만 인덱스에서 제거한다. 디렉터리는 -r 옵션이 필요하지만, 파일 하나에는 붙이지 않아도 된다. 아래 두 명령은 대상에 따른 대안이므로 실제로 제외할 경로에 맞춰 선택한다.
# 파일 하나를 추적 해제
git rm --cached -- .env
# 디렉터리 전체를 추적 해제하는 경우
git rm -r --cached -- logs/--cached를 사용하면 현재 작업 디렉터리의 파일은 남는다. 대신 인덱스에서는 파일이 빠지므로, 이미 커밋된 파일이라면 다음 커밋에 삭제 변경이 기록된다. 옵션 없이 실행하는 git rm은 작업 디렉터리의 파일도 삭제할 수 있으므로 구분해야 한다.
이후 무시 규칙을 스테이징하고 변경 범위를 검토한다. 인덱스와 작업 파일의 상태 차이 때문에 제거 명령이 거부된다면, 곧바로 강제 옵션을 붙이지 말고 기존 스테이징 내용부터 확인한다.
git add -- .gitignore
git status --short
git diff --cached --stat검토 결과에는 의도한 파일의 삭제와 .gitignore 변경이 포함되어야 한다. 기존에 다른 변경을 스테이징해 두었다면 그것도 다음 커밋에 들어갈 수 있으므로 함께 확인한다. 필요한 변경만 준비됐을 때 커밋하면 된다.
한두 파일의 문제를 해결하려고 저장소 전체에 git rm -r --cached .를 실행할 필요는 없다. 전체 인덱스를 비웠다가 다시 추가하면 검토할 변경 범위가 커지고, 원래 스테이징해 둔 작업을 구분하기도 어려워진다. 원인이 확인된 경로만 처리하는 편이 변경 의도를 설명하기 쉽다.
3. git rm --cached로 필요한 파일만 추적 해제하기
4. .gitignore 패턴 위치와 마지막 일치 규칙 확인하기
추적하지 않는 파일인데 무시되지 않는다면 패턴이 가리키는 범위를 살펴본다. 슬래시의 위치와 .gitignore가 놓인 디렉터리가 기준을 결정한다. 다음 표는 각 패턴이 저장소 최상위의 .gitignore에 있을 때의 차이다.
| 패턴 | 적용 범위 |
|---|---|
.env |
최상위와 하위 경로에 있는 같은 이름의 파일 또는 디렉터리 |
/.env |
저장소 최상위의 같은 이름 경로 |
logs/ |
최상위와 하위 경로의 logs 디렉터리 및 그 내용 |
/logs/ |
저장소 최상위의 logs 디렉터리 및 그 내용 |
*.log |
각 깊이에서 이름이 .log로 끝나는 파일 또는 디렉터리 |
같은 우선순위에서는 마지막으로 일치하는 패턴이 결과를 결정한다. 예를 들어 *.log 다음에 !important.log를 쓰면 해당 이름은 예외가 되지만, 그 뒤에 다시 *.log가 있으면 다시 무시된다.
하위 디렉터리의 .gitignore도 확인해야 한다. Git 공식 문서에 따르면 더 아래에 있는 파일의 규칙이 상위 규칙을 덮어쓸 수 있다. 규칙은 .git/info/exclude나 core.excludesFile 설정에서 올 수도 있으므로, 추측하며 파일을 편집하기보다 상세 출력의 출처를 먼저 보는 편이 빠르다.
4. .gitignore 패턴 위치와 마지막 일치 규칙 확인하기
5. 느낌표 예외 규칙이 안 될 때 부모 디렉터리 되살리기
!는 앞선 제외 규칙을 뒤집는 접두사다. 하지만 부모 디렉터리 자체가 제외되어 있으면 내부 파일 하나만 예외로 지정해도 다시 포함할 수 없다. Git이 제외된 디렉터리 내부를 탐색하지 않기 때문이다.
예를 들어 빌드 결과는 제외하면서 build/keep.txt만 저장소에 넣으려는 경우, 다음 구성은 의도대로 작동하지 않는다. 파일 예외보다 먼저 부모 디렉터리 전체가 제외되기 때문이다.
# 의도대로 작동하지 않는 구성
/build/
!/build/keep.txt직접 들어 있는 파일 하나만 남길 목적이라면 부모 디렉터리 대신 그 안의 항목을 제외한다. 이렇게 하면 build 자체는 탐색할 수 있고, 마지막 예외 규칙으로 대상 파일을 다시 포함할 수 있다.
# build 안의 항목은 제외하고 keep.txt는 허용
/build/*
!/build/keep.txt더 깊은 build/reports/summary.txt를 남기려면 중간 디렉터리도 열어줘야 한다. 다음처럼 탐색할 디렉터리를 예외로 되살린 뒤, 그 안에서는 다시 필요한 파일만 허용한다.
/build/*
!/build/reports/
/build/reports/*
!/build/reports/summary.txt패턴을 고친 뒤에는 디렉터리 이름만 검사하지 말고 실제로 남길 파일의 전체 경로를 검사한다. 예외 규칙은 파일을 자동으로 스테이징하지 않으므로, 저장소에 새로 넣을 파일은 별도의 git add가 필요하다.
git check-ignore -v --no-index -- build/reports/summary.txt
git status --short --untracked-files=all진단 관점에서 중요한 것은 추적 상태와 패턴 판정을 하나의 문제로 취급하지 않는 것이다. 추적 중인 파일은 인덱스 변경이 필요하고, 추적하지 않는 파일은 규칙 수정이 필요하다. 이 구분만 유지해도 강제 추가나 전체 인덱스 초기화 같은 우회 조치를 크게 줄일 수 있다.
5. 느낌표 예외 규칙이 안 될 때 부모 디렉터리 되살리기 조회하기
6. 추적 해제 후 로컬 파일·커밋 기록까지 확인하기
마지막 확인은 “변경 목록에서 사라졌는가”에 그치지 않는다. 현재 인덱스에서 빠졌는지, 무시 규칙이 맞는지, 다음 커밋에 의도한 변경만 들어가는지를 각각 확인해야 한다. 추적 해제한 .env라면 다음 순서로 점검할 수 있다.
git ls-files -- .env에서 경로가 출력되지 않는지 확인한다.git check-ignore -v -- .env에서 의도한 제외 패턴이 적용되는지 확인한다.- 현재 작업 디렉터리에
.env파일이 남아 있는지 확인한다. git status --short와git diff --cached --stat으로 커밋 범위를 검토한다.- 커밋 후
git status --short에서 남은 변경 사항을 확인한다.
git rm --cached가 로컬 파일을 보존한다는 설명은 명령을 실행한 현재 작업 디렉터리에 관한 것이다. 삭제 커밋을 다른 작업 환경에서 받아 반영하면 기존에 추적되던 파일이 작업 트리에서 제거될 수 있다. 팀이 함께 쓰던 설정 파일이라면 추적 해제 목적과 필요한 로컬 설정 준비를 함께 공유하는 것이 좋다.
운영 관점에서는 실제 비밀값이 없는 .env.example 같은 설정 예시를 추적하고, 로컬 전용 파일은 제외하는 방식이 유지보수에 도움이 된다. 다만 파일명만 예시로 바꾼다고 안전해지는 것은 아니므로, 공유할 내용에 실제 인증 정보가 없는지 확인해야 한다.
원인 확인은 추적 상태부터, 수정은 필요한 경로만 진행하면 된다. git ls-files로 현재 상태를 확인하고 git check-ignore로 규칙의 출처를 찾으면, 이미 추적 중인 파일 문제와 예외 패턴 문제를 명확하게 구분할 수 있다.
근거 문서: Git 공식 문서 gitignore의 설명·패턴 형식·우선순위 항목, git-check-ignore의 옵션·출력·종료 코드 항목. 본문의 수치는 공식 종료 코드와 명령 예시를 설명하는 데만 사용했으며, 근거 없는 적용률이나 성능 통계는 포함하지 않았다.