개인 메모 파일이 저장소를 오염시키는 일 방지

개발하다 보면 생기는 임시 노트, 설계 메모, 체크리스트 같은 파일들이 있다. 내 경우 _notes/ 디렉토리에 issue-site-plan.md 파일을 작업 중 만들어서 이슈 분석이나 계획을 정리했는데, 실수로 저장소에 커밋해버렸다. 이번 커밋은 그 파일을 untrack하고 .gitignore에 _notes/를 추가해서 앞으로 비슷한 일이 일어나지 않도록 정리한 작은 정리 커밋이다.

로컬 메모는 왜 저장소의 노이즈가 되나

프로젝트를 진행하다 보면 머리로만 생각하기보다는 파일에 메모를 한다. 이슈 분석, 아키텍처 스케치, 진행 상황 체크리스트 — 이런 것들은 개인의 생각 정리 과정의 일부다. 나 혼자 작업할 때야 괜찮지만, 팀이 코드를 공유하면 상황이 달라진다. 다른 팀원이 pull 받을 때 "왜 이 파일이 여기 있지?", "이건 누가 만들었고 언제 삭제하나?" 같은 혼동을 줄 수 있다. 더 심하면 누군가 그 메모를 팀 공식 문서로 착각할 수도 있다.

특히 깃 히스토리 관점에서도 문제다. 개인 메모 파일이 변경될 때마다 커밋이 생기면 실제 기능 변경과 무관한 노이즈가 저장소 히스토리에 쌓인다. git log를 볼 때 "어떤 커밋이 정말 중요한 변경인가"를 파악하기 어려워진다. 팀이 커질수록 이런 노이즈는 비용이 된다.

.gitignore로 로컬 파일 체계적으로 관리하기

내가 한 작업은 간단했다. 먼저 .gitignore에 다음 줄을 추가했다:

_notes/

이미 커밋된 _notes/issue-site-plan.md는 이 한 줄로는 untrack되지 않는다. 깃은 이미 tracking 중인 파일은 .gitignore 규칙을 적용하지 않기 때문이다. 따라서 다음 명령으로 명시적으로 제거했다:

git rm --cached _notes/issue-site-plan.md

--cached 플래그는 중요하다. 파일을 실제로 삭제하는 게 아니라, 깃 index에서만 제거한다는 뜻이다. 로컬 작업 파일은 내 컴퓨터에 남아 있고, 나중에 참고할 수 있다. 다만 더 이상 버전 관리의 대상이 아니게 된다.

이렇게 정리하는 일의 의미

이건 작은 "정리" 커밋처럼 보이지만, 팀 협업 관점에서는 중요한 신호다.

비슷한 실수를 방지하는 방법

내가 배운 건 .gitignore를 "사후 처리"로 보는 게 아니라, 프로젝트 시작할 때부터 의도적으로 설계해야 한다는 것이다. 팀이 일반적으로 만드는 로컬 파일들을 미리 정의해두고:

• _notes/ — 개인 설계/분석 메모
• .env.local, .env.*.local — 로컬 개발 환경 변수
• *.swp, .DS_Store — 에디터/OS 임시 파일
• build/, dist/ — 빌드 결과물
• node_modules/, .venv/ — 의존성

이런 규칙을 .gitignore에 사전에 포함하면, 새로운 팀원도 "아, 이런 파일들은 저장소에 올리는 게 아니구나" 하고 자연스럽게 따르게 된다. 리뷰어 입장에서도 이미 .gitignore로 필터링되면 코드 리뷰에 집중할 수 있다.

커밋 메시지에 "by mistake"라고 명시한 건 팀한테 "이건 의도된 정리"임을 알리려는 의도였다. 실수는 누구나 한다. 중요한 건 그걸 빨리 발견해서 정리하는 문화다. 이런 작은 정리 커밋들이 쌓이면 저장소가 건강해진다.

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

• 기계식키보드 쿠팡에서 보기 →
• 외장SSD 쿠팡에서 보기 →
• 커피머신 쿠팡에서 보기 →

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