.gitignore에 추가한 파일/경로의 변경사항이 출력될 때에 대한 해결방법 정리

Flutter 프로젝트에서 .gitignore가 제대로 동작하지 않을 때 해결하는 방법

Flutter 프로젝트를 시작하면서 가장 먼저 마주치는 것 중 하나가 .gitignore 파일 설정이다. 특히 .dart_tool/ 디렉터리는 Dart 도구들이 자동으로 생성하는 파일들이 담겨있어서 버전 관리에 포함할 필요가 없다. 당연히 .gitignore 파일에 .dart_tool/을 추가하면 Git이 무시할 것이라고 생각하기 마련이다. 그런데 여기서 문제가 발생한다.

분명히 .gitignore 파일에 .dart_tool/을 추가했는데도 git status를 실행하면 여전히 'untracked files' 목록에 .dart_tool/ 디렉터리가 나타나는 것이다. 이상하다. 분명히 설정했는데 왜 무시되지 않는 걸까?

문제의 원인

이런 현상이 발생하는 이유는 여러 가지가 있다. 내가 겪은 상황을 예로 들어보자.

1. .gitignore 파일의 변경사항이 아직 커밋되지 않은 경우

가장 흔한 실수다. .gitignore 파일에 무시할 파일이나 디렉터리를 추가했지만, 그 변경사항을 아직 커밋하지 않았다면 Git은 이전 버전의 .gitignore 파일을 기준으로 동작한다. 따라서 새로 추가한 무시 규칙이 적용되지 않는다.

# .gitignore 파일의 변경사항을 확인
git status

# .gitignore 파일을 커밋
git add .gitignore
git commit -m "chore: Update .gitignore to ignore .dart_tool directory"

2. 이미 Git에 의해 추적되고 있는 파일들

이게 진짜 골치 아픈 경우다. .gitignore 파일은 아직 추적되지 않은 파일들만 무시할 수 있다. 만약 .dart_tool/ 디렉터리 내부의 파일들이 이미 Git 저장소에 추가되어 추적되고 있다면, .gitignore에 추가해도 계속 추적된다.

이런 상황은 프로젝트 초기에 실수로 모든 파일을 git add .로 추가했거나, .gitignore 파일을 제대로 설정하기 전에 커밋을 했을 때 발생한다.

해결 방법

1. Git 인덱스 재설정

가장 확실한 방법은 Git의 인덱스(캐시)를 완전히 재설정하는 것이다. 이 방법은 로컬 파일은 그대로 두고 Git의 추적 목록만 초기화한다.

# Git 인덱스를 완전히 재설정
git rm -r --cached .
git add .

이 명령을 실행하면 Git이 모든 파일을 다시 검토하면서 .gitignore 규칙을 적용한다.

2. 특정 파일/디렉터리만 추적 중단

만약 특정 파일이나 디렉터리만 문제가 된다면, 해당 항목만 Git의 추적에서 제외할 수 있다.

# .dart_tool 디렉터리를 추적에서 제외
git rm -r --cached .dart_tool

# 또는 staged 상태에서 제거
git restore --staged .dart_tool/

3. .gitignore 파일 형식 확인

.gitignore 파일이 제대로 작성되었는지 확인하는 방법이 있다.

# 특정 파일이나 디렉터리가 무시되는지 확인
git check-ignore -v .dart_tool

# 성공하면 다음과 같은 출력이 나온다:
# .gitignore:16:.dart_tool    .dart_tool

만약 아무 출력이 없거나 오류가 발생한다면 .gitignore 파일에 문제가 있는 것이다.

내가 겪은 실제 해결 과정

1. 문제 발견: git status에서 .dart_tool/이 계속 'untracked files'에 나타남
2. 첫 번째 시도: .gitignore 파일 확인 → 이미 .dart_tool/이 추가되어 있음
3. 두 번째 시도: git check-ignore -v .dart_tool → 아무 출력 없음 (문제 있음)
4. 원인 파악: .gitignore 파일 마지막 줄의 형식 오류 발견
5. 해결:
   • Git 인덱스 재설정: git rm -r --cached . && git add .
   • .dart_tool/을 staged에서 제거: git restore --staged .dart_tool/
   • .gitignore 파일 형식 수정
   • 변경사항 커밋

최종 확인

모든 작업이 끝나면 다음 명령어들로 제대로 동작하는지 확인할 수 있다:

# 1. git status에서 .dart_tool/이 더 이상 나타나지 않는지 확인
git status

# 2. .dart_tool이 제대로 무시되는지 확인
git check-ignore -v .dart_tool
# 출력: .gitignore:16:.dart_tool    .dart_tool

# 3. .gitignore 파일 형식 확인
cat .gitignore | grep dart_tool

마무리

.gitignore 파일이 제대로 동작하지 않는 문제는 생각보다 복잡할 수 있다. 단순히 파일에 항목을 추가하는 것만으로는 해결되지 않는 경우가 많다. 특히 이미 Git에 의해 추적되고 있는 파일들은 별도의 작업이 필요하다.

가장 중요한 것은 .gitignore 파일을 프로젝트 시작 단계에서 제대로 설정하는 것이다. Flutter 프로젝트라면 flutter create 명령어로 생성할 때 기본적으로 제공되는 .gitignore 파일을 사용하고, 필요에 따라 추가 항목을 더하는 것이 좋다.

그리고 혹시 .gitignore 파일이 제대로 동작하지 않는다면, 당황하지 말고 차근차근 원인을 찾아보자. 대부분은 위에서 언급한 몇 가지 원인 중 하나일 것이다.