로컬 캐시 파일이 repo를 오염시키던 문제 해결

개발 도구의 로컬 session state 파일들이 실수로 git에 커밋되어 있던 걸 정리했다. .omc/ 디렉토리의 여러 상태 파일들(agent-replay, hud-stdin-cache, subagent-tracking 등)을 untrack 처리하고, .gitignore에 명시해 앞으로는 같은 실수가 반복되지 않도록 했다.

왜 이런 일이 발생했나

로컬 개발 환경에서만 필요한 임시 상태 파일이 실수로 git에 포함되는 건 아주 흔한 문제다. 특히 개발 초기에 프로젝트를 셋업할 때, IDE 플러그인이나 로컬 개발 도구가 생성하는 캐시/상태 디렉토리들을 모두 .gitignore에 등록하기 전에, 누군가는 한 번이라도 git add . 같은 넓은 범위 명령어를 실행하곤 한다. 그러면 그 시점의 상태 파일이 snapshot으로 repo에 박혀서 이후로 계속 따라다닌다.

.omc/는 아마도 로컬 개발 환경의 핵심 도구와 관련된 session replayer나 HUD 상태를 추적하는 디렉토리인 듯하다. 이런 파일들은 각자의 개발 환경에서만 의미가 있고, 팀 전체가 공유해야 할 상태가 아니다.

이렇게 방치하면 뭐가 문제인가

단순해 보이지만 몇 가지 실질적인 문제가 생긴다:

1. 충돌 유발 — 팀원들이 각자 로컬에서 작업할 때, 각자 다른 session state를 가지게 된다. 그 상태 파일들이 계속 git에 추적되면 merge conflict가 불필요하게 발생한다. 특히 CI/CD 파이프라인이나 로컬 테스트 중에 이 파일들이 변경되면 "이건 뭔 conflict인가" 싶은 경험을 반복하게 된다.

2. Repository 크기 증가 — 대수롭지 않아 보이지만, 시간이 지나면서 매번 이 파일들이 업데이트되면서 git history에 누적된다. 특히 JSON 파일 같은 경우 diff가 커서 git pack 파일이 불필요하게 팽창한다. clone 속도도 느려진다.

3. Commit history 노이즈 — 정말 의미 있는 변경들 속에 "자동으로 생성된 상태 파일 업데이트" 같은 commit이 섞여 있으면, 나중에 blame이나 히스토리를 추적할 때 신호 대비 노이즈가 심해진다.

정리 작업과 패턴

# 이미 커밋된 파일들을 untrack 처리
git rm --cached .omc/state/*

# .gitignore에 패턴 추가
echo ".omc/" >> .gitignore

이게 전부인데, 중요한 건 두 가지 단계를 나누어야 한다는 것:

첫 번째 단계 없이 .gitignore만 추가하면, 이미 커밋된 상태 파일들은 계속 추적된다. 그래서 둘 다 필요한 거고, 순서도 중요하다.

회고와 배운 점

이런 문제는 사실 프로젝트 초기 설계 단계에서 방지해야 한다. 새로운 프로젝트를 시작할 때, .gitignore를 먼저 설계하는 체크리스트가 있어야 한다:

• 빌드 산출물 (node_modules, dist, build 등)
• IDE/에디터 설정 (.vscode, .idea, .DS_Store 등)
• 로컬 환경 설정 (.env.local, secrets)
• 개발 도구 캐시 (.omc/, .cache/, 그 외 플러그인 상태)
• 임시 파일 (.tmp, *.log)

또 하나 배운 점은, 이런 상황은 pre-commit hook이나 git hooks로도 미리 방지할 수 있다는 것. 예를 들어:

# pre-commit hook 예시
git diff --cached --name-only | grep -E "\.omc/|\.cache/" && {
  echo "Error: Do not commit tool cache files"
  exit 1
}

이렇게 hook을 설정하면, 실수로 상태 파일을 add했더라도 commit 단계에서 걸린다.

마지막으로, 팀 규모가 커질수록 이런 "작은 정리"는 누적되면 무시할 수 없는 기술 부채가 된다. 각자 로컬에서 .omc/ 상태 파일 diff를 보면서 "이거 왜 자꾸 충돌하지?" 하는 경험이 반복될 때마다, 누군가는 결국 정리 commit을 해야 한다. 그래서 되도록 초반에 깔끔하게 하는 게 시간과 정신력을 절약한다.

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

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

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