무엇을 무시하고 무엇을 커밋할까

좋은 .gitignore는 길이가 아니라 기준으로 판단한다. 기준은 하나다. 저장소를 새로 clone한 사람이 소스와 설정만으로 같은 결과를 다시 만들 수 있는가. 다시 만들 수 있는 것은 무시하고, 다시 만들 수 없거나 결과를 고정하는 것은 커밋한다.

무시할 것

종류	예	이유
빌드 산출물	`dist/`, `build/`, `target/`, `.o`, `.class`	소스에서 다시 만든다
의존성 설치 결과	`node_modules/`, `vendor/`(PHP), `.venv/`	매니페스트와 lockfile로 다시 설치한다
캐시·로그	`.cache/`, `.pytest_cache/`, `*.log`, `coverage/`	실행할 때마다 바뀐다
로컬 환경·비밀	`.env`, `.pem`, `local.properties`, `.tfstate`	사람·환경마다 다르거나 유출되면 안 된다
개인 도구 상태	`.DS_Store`, `*.swp`, `.idea/workspace.xml`	프로젝트와 무관하다 (전역 gitignore 권장)

lockfile: package-lock.json, yarn.lock, pnpm-lock.yaml, Cargo.lock, poetry.lock, uv.lock, Gemfile.lock, composer.lock, go.sum, .terraform.lock.hcl. 모두가 같은 버전으로 설치하게 해 준다. 템플릿 중에는 Angular처럼 lockfile을 무시하는 것도 있으니 결과를 확인한다.
예시 설정: .env.example, config.example.yml. 어떤 값이 필요한지 알려 주되 실제 비밀은 담지 않는다.
빌드 도구 래퍼: gradlew와 gradle/wrapper/, mvnw. Java 템플릿의 *.jar 때문에 래퍼 jar가 무시되지 않았는지 확인한다.
팀이 합의한 에디터 설정: .editorconfig, .vscode/settings.json, .vscode/extensions.json, .idea/codeStyles/. 포매팅과 린트 설정을 공유하면 리뷰가 쉬워진다.

.gitignore는 루트에만 둘 수 있는 것이 아니다. 하위 디렉터리의 .gitignore는 그 디렉터리를 기준으로 동작하고, 상위 파일보다 우선한다. 모노레포에서 패키지마다 필요한 규칙이 다르다면 패키지 폴더에 따로 두는 것이 읽기 쉽다.

repo/
├── .gitignore          # 공통: .DS_Store, .env, coverage/
├── apps/web/.gitignore # .next/, out/
└── services/api/.gitignore # target/

git은 파일만 추적하고 빈 디렉터리는 저장하지 않는다. 로그 폴더처럼 폴더는 있어야 하지만 내용은 무시하려면 폴더 안에 표시 파일을 두고 부정 규칙으로 살린다.

/log/*
!/log/.keep

.keep이나 .gitkeep이라는 이름은 git의 공식 기능이 아니라 관례일 뿐이다. 어떤 이름이든 동작한다. 또 다른 방법으로, 그 폴더 안에 다음 내용의 .gitignore를 두면 자기 자신만 남기고 나머지를 무시한다.

*
!.gitignore

언어·프레임워크 1~2개 + OS + 에디터 조합이 일반적이다. OS·에디터 규칙은 전역에 두었다면 생략해도 된다.
순서를 확인한다. 부정 규칙이 들어 있는 템플릿(Gradle, VisualStudioCode)은 넓은 규칙을 가진 템플릿(Java, Kotlin)보다 뒤에 둔다.
중복 제거는 의미를 지키는 방식으로. 같은 규칙이 반복돼도 동작은 같지만 읽기 어렵다. 이 사이트의 생성기는 사이에 부정 규칙이 없을 때만 중복을 지운다.
섹션 주석을 남긴다. 몇 달 뒤 어떤 규칙이 어디서 왔는지 알 수 있어야 안전하게 지울 수 있다.
테스트한다. git ls-files로 뽑은 실제 경로를 패턴 테스트에 넣어 의도하지 않은 파일(예: Python 템플릿의 lib/에 걸린 프런트엔드 코드)이 무시되지 않는지 확인한다.

*.json처럼 너무 넓은 규칙은 설정 파일까지 삼킨다. 가능한 한 경로를 좁히고(/dist/), 디렉터리에는 끝 슬래시를 붙여 같은 이름의 파일과 구분한다. 규칙 위에 한 줄 주석으로 이유를 적어 두면 다음 사람이 지워도 되는지 판단할 수 있다.