Git을 사용할 때 ‘무엇을 추적할 것인가’ 만큼이나 중요한 것이 **’무엇을 추적하지 않을 것인가’**입니다. 프로젝트가 진행될수록 불필요한 파일들이 저장소를 어지럽히거나, 보안상 민감한 정보가 실수로 업로드되는 사고를 방지하기 위해 .gitignore 설정은 필수적입니다. 본 글에서는 .gitignore의 패턴 작성법부터, 이미 추적 중인 파일을 제외하는 고급 트러블슈팅까지 상세히 다룹니다.
.gitignore란 무엇인가?
.gitignore 파일은 Git이 추적(Track)하지 말아야 할 파일이나 폴더의 목록을 정의하는 텍스트 파일입니다. Git은 기본적으로 작업 디렉토리 내의 모든 파일을 관리 대상으로 간주하려 하지만, 이 파일에 명시된 규칙에 해당하는 파일들은 git status 명령어 실행 시에도 나타나지 않으며, git add 시에도 자동으로 제외됩니다.
왜 설정해야 하는가?
- 보안 유지: API Key, 데이터베이스 비밀번호가 포함된 설정 파일이 공개 저장소에 올라가는 것을 막습니다.
- 저장소 경량화: 빌드 결과물(.class, .jar, /build 등)이나 로그 파일 등 불필요한 대용량 파일이 저장소 용량을 차지하는 것을 방지합니다.
- 협업 효율성: 개발자 개인의 IDE 설정 파일(.idea, .vscode 등)이나 운영체제 생성 파일(.DS_Store)이 동료의 작업 환경과 충돌하는 것을 막습니다.
.gitignore 패턴 작성 문법 (Syntax)
.gitignore는 표준 Glob 패턴을 사용합니다. 아래는 실무에서 가장 자주 사용되는 5가지 핵심 문법입니다.
1. 특정 파일 및 확장자 제외 가장 기본적인 형태입니다.
file.txt: 특정 이름의 파일을 제외합니다.*.log: 확장자가.log인 모든 파일을 제외합니다.*.class: 컴파일된 클래스 파일을 모두 제외합니다.
2. 디렉토리 제외 폴더 이름 뒤에 슬래시(/)를 붙여 디렉토리 전체를 제외함을 명시합니다.
build/: build 폴더와 그 안의 모든 내용을 무시합니다.node_modules/: Node.js 프로젝트의 의존성 폴더를 무시합니다.
3. 위치 고정 (Anchor) 슬래시의 위치에 따라 적용 범위가 달라집니다.
/temp:.gitignore파일이 있는 현재 디렉토리의 temp 폴더만 무시합니다. (하위 폴더의 temp는 무시하지 않음)temp/: 프로젝트 내 어디에 있든 temp라는 이름의 폴더는 모두 무시합니다.
4. 예외 처리 (Negation) 느낌표(!)를 사용하여 무시 목록에서 특정 파일만 다시 추적 대상으로 지정합니다.
# 모든 .a 파일을 무시 *.a # 하지만 lib.a 파일은 무시하지 않고 추적함 !lib.a
5. 더블 아스표 (Double Asterisk) **는 여러 디렉토리 계층을 의미합니다.
logs/**/debug.log: logs/debug.log, logs/monday/debug.log, logs/year/month/debug.log 등 모든 깊이의 debug.log를 무시합니다.
실무 언어별 .gitignore 예시
프로젝트 생성 시 매번 작성하기 번거롭다면, 언어별 표준 템플릿을 참고하는 것이 좋습니다.
Java (IntelliJ 포함) 예시
# Compiled class file *.class # Log file *.log # Package Files *.jar *.war *.ear # IntelliJ IDEA .idea/ *.iml # Build folder target/ build/
Python 예시
# Byte-compiled / optimized / DLL files __pycache__/ *.py[cod] *$py.class # Virtual Environments venv/ env/ # Distribution / packaging dist/ build/
JavaScript (Node.js) 예시
# Dependency directories node_modules/ jspm_packages/ # Build Outputs dist/ # Env files (Security) .env
문제 해결: .gitignore가 작동하지 않을 때
가장 흔하게 겪는 문제는 **”.gitignore에 파일을 추가했는데도 여전히 git status에 나타나거나 추적되는 경우”**입니다.
원인 분석 Git은 이미 추적(Tracking)되고 있는 파일은 .gitignore에 추가하더라도 무시하지 않습니다. 즉, 이전에 한 번이라도 git add나 git commit이 된 파일은 .gitignore의 영향을 받지 않습니다.
해결 방법 (캐시 삭제) Git의 내부 인덱스(Cache)에서 해당 파일을 제거한 후 다시 커밋해야 합니다. 파일 자체를 삭제하는 것이 아니라, 추적 상태만 해제하는 것입니다.
- 단일 파일 처리 이 명령어를 실행하면 파일은 로컬 디렉토리에 그대로 남지만, Git의 추적 대상에서는 제외됩니다.
git rm --cached <파일명>
- 전체 적용 (권장)
.gitignore를 대대적으로 수정한 경우, 전체 캐시를 비우고 다시 적용하는 것이 깔끔합니다..gitignore에 정의된 파일들은 깔끔하게 무시됩니다.
# 1. 모든 파일의 스테이징(추적) 해제 (파일은 삭제되지 않음) git rm -r --cached . # 2. .gitignore 규칙에 따라 다시 스테이징 git add . # 3. 변경 사항 커밋 git commit -m "Apply .gitignore rules"
팁: 전역(Global) .gitignore 설정하기
프로젝트마다 .DS_Store(macOS)나 Thumbs.db(Windows) 같은 OS 시스템 파일을 매번 설정하는 것은 번거롭습니다. 내 컴퓨터의 모든 Git 프로젝트에 공통적으로 적용될 규칙을 설정할 수 있습니다.
- 홈 디렉토리에 설정 파일 생성
touch ~/.gitignore_global
- 파일 내부에 공통적으로 무시할 패턴 작성 (.DS_Store 등)
- Git 설정에 등록
git config --global core.excludesfile ~/.gitignore_global
요약
.gitignore는 단순한 제외 목록이 아니라 프로젝트의 품질과 보안을 지키는 첫 번째 방어선입니다. 프로젝트 초기 단계에 확실하게 설정해두어야 추후 꼬인 인덱스를 정리하는 수고를 덜 수 있습니다. 이미 추적 중인 파일이 무시되지 않을 때는 당황하지 말고 git rm --cached 명령어를 기억하십시오.