개발 도구 임시 파일이 커밋되던 문제 해결

어느 날 저장소를 정리하다가 발견했다. .omc/ 디렉토리 아래로 뭔가 잔뜩 쌓여 있었다. agent replay 로그, hud 캐시, 세션 상태 파일들. 모두 로컬 개발 도중에 자동으로 생기는 임시 파일인데, 실수로 git이 추적하고 있었던 것. 이번 작업은 그 파일들을 저장소에서 제외하고, 향후 반복되지 않도록 .gitignore를 정리하는 chore였다.

왜 이런 일이 발생하는가

개발 도구(특히 에이전트, 빌드 시스템, IDE 플러그인)는 대부분 상태 파일을 로컬에 저장한다. 캐시, 로그, replay 정보, 세션 토큰 같은 것들이다. 이런 파일들은:

• 개발자마다 다르다. 내 환경에서 생기는 replay 로그는 팀원의 환경과 다를 수 있다.
• 협력할 때 충돌을 일으킨다. 특히 JSON 상태 파일은 merge할 때마다 불필요한 diff가 생긴다.
• 프로덕션에 영향 없다. 로컬 개발 편의를 위한 것일 뿐, 배포 결과물과는 무관하다.

이번의 .omc/state/ 아래 파일들도 그 예. agent replay 로그는 디버깅할 때 쓸모 있지만, 팀 전체가 공유할 필요는 없다. 오히려 저장소가 bloat되고, "왜 이 파일이 변경됐지?" 하는 불필요한 질문만 늘어난다.

어떻게 정리했는가

먼저 현재 상태를 확인해보자. 이미 실수로 커밋된 파일들을 git의 추적에서 빼는 방법은 두 가지다:

방법 1: git rm --cached로 추적 중단

git rm --cached .omc/state/agent-replay-dec99fe2-17a9-430b-9a24-06371c0af60f.jsonl
git rm --cached .omc/state/hud-stdin-cache.json
# ... 등등

이 방법은 파일은 로컬에 남겨두되, git의 추적만 그만둔다. 개발자들이 계속 그 파일을 사용하면서도, 저장소에는 기록되지 않게 한다.

방법 2: .gitignore에 패턴 추가

.omc/state/

또는 더 구체적으로:

.omc/state/**/*.jsonl
.omc/state/**/*.json

나는 둘을 조합했다. 이미 커밋된 파일들은 git rm --cached로 언트래킹하고, .gitignore에 .omc/state/ 전체를 추가해서 향후 이 디렉토리 아래 어떤 파일이 생기든 자동으로 제외되도록 했다. 이렇게 하면 누군가 새로운 로컬 도구를 설치해도, 그 도구의 상태 파일이 실수로 커밋될 일이 없다.

이런 실수를 어떻게 방지하나

프로젝트 초기에 .gitignore를 철저히 설계하는 게 최선이다. 하지만 현실은 복잡하다. 도구가 업데이트되고, 새로운 플러그인이 추가되고, 팀이 성장하면서 예상하지 못한 파일들이 생기기 때문이다.

내가 배운 패턴은 이렇다:

1. CI에서 생기는 파일은 우선 제외하자. CI가 실행될 때마다 로그나 캐시를 생성한다면, 그건 100% 제외해야 한다. 누군가는 반드시 실수로 커밋할 테니.

2. "상태"라는 이름이 붙은 파일은 의심하자. state, cache, session, log 같은 이름은 거의 항상 로컬 개발용이다. 코드 리뷰할 때 이런 파일이 보이면 바로 잡아낸다.

3. 팀 규칙을 명시하자. 문서화 해두는 게 좋다. ".omc/는 로컬 도구용이므로 커밋하지 않습니다" 같은 간단한 노트.

4. 개인 exclude vs 공유 gitignore의 트레이드오프. .git/info/exclude는 개인 개발 환경에만 적용되고, .gitignore는 팀 전체가 공유한다. 개인 특화 파일(내 IDE 설정, 내 로컬 임시 디렉토리)은 exclude에 넣고, 팀 전체가 겪을 만한 파일(빌드 산물, 도구 캐시)은 gitignore에 넣는 게 일반적이다. 이 경우 .omc/state/는 팀 도구에서 나오는 파일이니 .gitignore가 맞다.

다음

이런 작은 정리 작업이지만, 저장소의 신경쓰임을 덜어낸다. 특히 팀이 커질수록, 도구가 많아질수록 이런 관리가 중요해진다. 누군가 PR을 열었을 때 "어? 이 파일 왜 안 바꼈는데 diff에 떠?" 하는 혼동이 없어진다.

다음부터는 새로운 로컬 도구를 도입할 때 바로 이전에 .gitignore 상황을 먼저 점검하는 습관을 들이려고 한다.

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

• 기계식키보드 쿠팡에서 보기 →
• 외장SSD 쿠팡에서 보기 →
• 모니터 쿠팡에서 보기 →

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