빌드 캐시 파일을 깃 추적에서 제거해 코드 리뷰 노이즈를 줄인 이야기

TypeScript 빌드 캐시 파일인 .tsbuildinfo를 git에서 언트랙하고 .gitignore에 추가했다.

생성 파일이 git 추적 대상이 되는 이유

개발하면서 자주 보는 문제인데, TypeScript의 incremental build 캐시인 .tsbuildinfo 파일이 repo에 커밋되어 있었다. 초기 프로젝트 세팅할 때는 주의하지 못했지만, 팀 규모가 커지면서 문제가 눈에 띄기 시작했다.

로컬 개발 환경, CI 서버, 각 팀원의 머신에서 생성되는 .tsbuildinfo는 빌드 타이밍, TypeScript 버전, 환경 변수, 심지어 파일 시스템까지 영향을 받는다. 그러면 어떤 일이 발생하나?

• 의도하지 않은 변경으로 감지: PR 올릴 때마다 .tsbuildinfo가 diff에 포함돼서 실제 코드 변경과 섞임
• 병합 충돌: 여럿이 빌드하면 충돌이 불가피. 해결도 어려움 (이진 파일이나 다름없는 구조)
• 히스토리 오염: git blame이나 log를 볼 때 의미 없는 커밋이 쌓임
• 팀의 인지 부하: "이게 뭐 바뀐 거예요?" 같은 질문이 반복

왜 지금 처리했나

파일을 역추적해 보니 아마 초기 빌드 후 실수로 올라갔을 가능성이 크다. 작은 변화 같지만, 팀이 성장할수록 이런 파일 하나가 매일 여러 번 발동한다. 코드 리뷰 시점에 진짜 의도한 변경을 찾는 데 방해가 되고, 초입에서 정리하는 게 나중에 정리하는 것보다 훨씬 쉽다.

생성 파일 관리의 일반론

이 패턴은 TypeScript 프로젝트뿐 아니라 대부분의 빌드 시스템에서 반복된다. 예를 들면:

• JavaScript: node_modules, .next, dist, .parcel-cache
• Java: target/, build/
• Go: vendor/ (의존도에 따라)
• Rust: target/
• IDE/Editor: .vscode/, .idea/, *.swp

공통점이 뭔가? 모두 로컬 빌드/개발 과정에서 자동 생성되고, 환경마다 내용이 다르다. git은 정확하게 상태를 추적하는 도구인데, 이런 파일까지 추적하면 "추적할 가치가 있나?"라는 질문이 생긴다.

# TypeScript
*.tsbuildinfo

# 또는 더 세분화하면
apps/*/tsconfig.tsbuildinfo

이런 건 프로젝트 초기에 .gitignore를 제대로 구성하면 피할 수 있는 실수인데, 기존 프로젝트에 합류하면 이미 추적되고 있는 경우가 많다. 그럼 이미 추적되는 파일을 제외하려면?

git rm --cached apps/web/tsconfig.tsbuildinfo

그다음 .gitignore에 패턴을 추가한 후 커밋. 이 작은 정리 작업이 팀의 개발 경험을 한 단계 개선하는 거다.

회고

솔직히 "파일 하나 빼는 것"이라고 하면 자잘한 작업 같다. 하지만 팀이 커질수록 이런 것들이 쌓인다. 모든 팀원이 매일 여러 번 부딪히는 작은 마찰들이, 각각 5초씩이지만 월단위로는 상당한 시간이 된다. 그리고 그 시간이 "왜 이 파일이 변경됐지?" 같은 인지 부하로 돌아온다.

리드로 일하면서 느꼈는데, 이런 정리 작업은 "지금 당장 뭔가 깨졌나?"는 아니지만, "개발 환경의 위생"이라는 관점에서는 중요하다. 코드의 가독성, 구조, 성능만큼 "git history의 신뢰성"도 팀의 자산이다. 변경사항을 볼 때 의미 있는 것들만 보인다면, 코드 리뷰도, blame도, 이력 분석도 훨씬 수월해진다.

🛒 이 글과 어울리는 추천 상품

• 노트북 쿠팡에서 보기 →
• 외장SSD 쿠팡에서 보기 →
• 모니터 쿠팡에서 보기 →

*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.