말 그대로입니다. .gitignore 파일이 기대한 대로 작동하지 않아 골치를 앓고 있는 경우가 생각보다 많습니다.
.gitignore 파일은 Git 저장소에서 매우 중요한 역할을 합니다. 이 파일이 제대로 작동하지 않으면 비공개로 유지해야 할 변경 사항이 실수로 추적될 수 있습니다. 심한 경우 API 키 같은 민감한 정보가 저장소에 노출될 위험도 있습니다.
.gitignore 파일이 작동하지 않는 대표적인 원인은 두 가지입니다:
- 파일을 이미 커밋한 후에 .gitignore에 추가한 경우
- .gitignore 파일에서 잘못된 파일 이름이나 경로를 참조한 경우
이 글에서는 두 가지 문제를 하나씩 살펴보고 해결 방법까지 자세히 안내해 드립니다.
.gitignore 파일이란?
.gitignore 파일은 Git 저장소에 저장하고 싶지 않은 파일들의 목록을 담고 있는 파일입니다. 주로 설정 파일이나 환경 파일을 저장소 외부에 보관하는 용도로 사용되며, 이런 파일들은 개인 정보를 포함하는 경우가 많아 원격 저장소에 올라가서는 안 됩니다.
이 파일은 반드시 .gitignore라는 이름으로 정확하게 생성하고 저장해야 합니다. 이 일반 텍스트 파일에 Git이 추적하지 않기를 원하는 파일이나 디렉터리의 경로를 추가하면 됩니다. 이 파일에 추가된 모든 항목은 Git이 무시하며 추적 트리에 포함되지 않습니다.
다음은 .gitignore 파일 내용의 예시입니다:
node_modules/ .env
위 설정은 Git에게 특정 파일을 무시하라고 지시하는 것입니다. 여기서는 API 키가 자주 담기는 .env 파일과, 설치된 NPM 패키지가 모두 들어 있는 node_modules 폴더를 무시하도록 했습니다.
일반적으로 무시하는 파일로는 .DS_Store 파일, .env 파일,各종 설정(config) 파일 등이 있습니다. 특히 .DS_Store 파일은 macOS 환경에서 자동으로 생성되며 Git 저장소에 포함될 필요가 전혀 없습니다.
대부분의 .gitignore 파일은 저장소의 루트 디렉터리에 위치합니다. .gitignore 작성법을 더 깊이 알고 싶다면 초보자용 .gitignore 가이드를 참고해 보세요.
시나리오 A: 커밋한 후에 .gitignore에 파일을 추가한 경우
무시했어야 할 파일을 실수로 커밋한 뒤에야 .gitignore에 추가하고, 그런데도 Git이 계속 파일을 추적한다고 불평하는 경우가 흔합니다.
원인은 간단합니다. 파일/폴더는 커밋하기 전에 .gitignore에 추가해야 하기 때문입니다. Git은 이미 해당 파일을 추적 중이므로, 추적을 해제하려면 다음 명령어를 실행해야 합니다:
git rm -rf --cached <path>
앞부분의 git rm은 지정한 <path>를 제거합니다. --cached 플래그는 인덱스(스테이징 영역)에서만 제거하고 로컬 디렉터리에는 파일을 그대로 남겨둡니다. -r은 디렉터리 경로를 재귀적으로 제거하는 옵션이고, -f는 강제 실행 옵션입니다. 단일 파일만 다루면서 로컬에는 파일을 유지하고 싶다면 아래처럼 입력하세요:
git rm --cached <file>
이렇게 하면 Git에게 더 이상 해당 파일/폴더를 추적하지 않겠다고 알려주는 셈입니다. 이후 다시 시도하면 .gitignore가 정상적으로 작동할 것입니다. 단, .gitignore가 작동하려면 무시할 파일/폴더를 정확히 지정해야 한다는 점을 잊지 마세요!
시나리오 B: 커밋 전에 .gitignore를 만들었는데도 파일이 추적되는 경우
.gitignore가 여전히 파일을 무시하지 못한다면, 해결책은 의외로 간단할 수 있습니다. 바로 올바른 파일을 참조하고 있는지 확인하는 것입니다. .gitignore가 무시할 파일을 정확하게 지정해야 하며, 철자 오류나 잘못된 경로는 직접 수정해 주어야 합니다.
다음 예시를 살펴보세요:
*.pyyc
이 .gitignore 규칙은 Git에게 .pyyc 확장자를 가진 모든 파일을 무시하라고 지시합니다. 하지만 원래 의도는 .pyc 파일을 무시하는 것이었습니다. .pyc 파일은 Python 프로그램이 컴파일될 때 생성되는 바이트코드 파일입니다. .gitignore는 의도를 알 수 없으므로 규칙을 수정해야 합니다:
*.pyc
이제 저장소는 모든 .pyc 파일을 정상적으로 무시할 것입니다.
추가로, 파일/폴더 선언 앞뒤에 불필요한 공백(trailing space)이 없는지도 꼭 확인하세요. 눈에 잘 띄지 않지만 의외로 흔한 원인입니다.
결론
지금까지 .gitignore가 예상대로 작동하지 않는 다양한 상황과 해결 방법을 살펴보았습니다. 핵심은 파일/디렉터리의 위치를 정확히 파악해 올바른 경로를 지정하는 것입니다.
무시해야 할 파일은 생성되는 즉시 .gitignore에 추가하는 습관을 들이는 것이 좋습니다. 만약 실수로 커밋했다면 다행히 git rm -rf --cached <path> 명령어가 있습니다. 이 명령어로 파일을 Git 추적 대상에서 제거한 뒤, .gitignore에 추가하면 이후부터는 정상적으로 무시됩니다.
마지막 참고 사항: 상황에 따라 git reset이 유용할 수도 있습니다. git reset은 마치 실행 취소처럼 이전 시점으로 되돌리는 기능이므로, 어떤 경우에는 바로 그것이 필요한 해결책이 될 수 있습니다.
Git을 더 깊이 배우고 싶으신가요? How to Learn Git 가이드를 확인해 보세요. Git 학습에 대한 전문가 조언과 추천 학습 리소스를 정리해 두었습니다.