Git 저장소를 오래 운영하다 보면 히스토리 자체를 손봐야 하는 순간이 온다. 실수로 커밋된 대용량 파일이나 비밀 키를 과거 이력에서까지 완전히 제거해야 하거나, 모노레포의 특정 디렉터리만 떼어내 별도 저장소로 옮겨야 하는 경우다. 이런 작업의 표준 도구로 오랫동안 쓰인 것이 git filter-branch였지만, 지금은 git 프로젝트 스스로가 이 명령을 더 이상 쓰지 말라고 권고하며 대안으로 git filter-repo를 지목하고 있다. filter-repo는 filter-branch를 대체하기 위해 만들어진 히스토리 재작성 도구로, 성능과 안전성, 기능 범위 모든 면에서 기존 도구들의 한계를 넘어서는 것을 목표로 설계됐다.
왜 filter-branch를 버려야 하나
filter-branch가 밀려난 이유는 명확하다. 우선 조금이라도 규모가 있는 저장소에서는 처리 속도가 마땅히 나와야 할 수준보다 여러 자릿수 느려, 실제 작업에서 감당하기 어려운 경우가 많다. 게다가 곳곳에 함정이 숨어 있어, 사용자가 의도한 정리 작업이 조용히 어긋나거나 오히려 원래보다 더 지저분한 결과물을 남기기도 한다. 조금만 복잡한 재작성을 하려 해도 명령을 구성하는 일 자체가 대단히 번거롭다. git 프로젝트는 이런 문제들이 하위 호환성을 지키면서는 고칠 수 없는 구조적 결함이라고 못박았고, 그래서 사용 중단을 공식 권고하기에 이르렀다.
또 다른 대안이었던 BFG Repo Cleaner에 대해서도 filter-repo 측은 냉정하게 평가한다. 당대에는 훌륭한 도구였고 일부 작업을 간단하게 만들어 줬지만, 처리할 수 있는 재작성 유형이 몇 가지로 제한되며 그 구조상 더 다양한 요구를 수용하기 어렵고, 본래 용도 안에서도 몇몇 단점과 버그를 안고 있다는 것이다. 예컨대 저장소의 한 조각을 떼어내 다른 큰 저장소에 병합할 목적으로 추출하는 작업은 BFG의 능력 범위를 완전히 벗어난다. 반면 filter-repo에서는 접두사를 붙여 경로를 재배치하는 한 줄짜리 명령으로 같은 일을 처리할 수 있다.
사용성을 앞세운 설계
filter-repo가 내세우는 차별점은 단순한 속도 개선이 아니라 사용자 관점의 설계다. --analyze 같은 플래그로 첫 실행 시 저장소 분석 리포트를 제공해, 무엇을 지우고 이름을 바꿔야 할지 사용자가 어림짐작하지 않게 돕는다. 경로를 제거하는 기능뿐 아니라 특정 경로만 남기는 기능을 별도로 제공해, 저장소 역사에 존재했던 모든 경로를 일일이 나열해야 하는 고통을 덜어 준다. 서브디렉터리를 저장소의 루트로 끌어올리거나 반대로 루트를 서브디렉터리로 내리는 등의 이름 변경도 손쉽고, 이 과정에서 여러 파일이 같은 경로로 겹치는 상황은 안전성 검사로 잡아낸다.
안전장치의 철학도 실용적이다. 원본 참조를 저장소 내 특수 네임스페이스에 백업하는 방식은 실제 복구에 서툰 사용자가 대부분이라 그다지 도움이 되지 않는다. 그래서 filter-repo는 신선한 클론이 아닌 곳에서 실행하면 아예 중단해 버리고, 사용자가 --force로 명시적으로 덮어써야만 진행한다. 문제가 생기면 클론을 통째로 지우고 다시 받는, 누구나 아는 가장 쉬운 복구 방식을 유도하는 것이다. 또한 필터링이 끝나면 기본적으로 오래된 객체를 정리하고 저장소를 리팩(repack)해, filter-branch 매뉴얼의 다단계 축소 절차가 실제로는 작동하지 않던 문제를 피한다. 새 히스토리와 옛 히스토리가 섞여 실수로 다시 푸시되는 사고도 구조적으로 차단한다.
도구를 넘어 라이브러리로
filter-repo가 특히 돋보이는 지점은 확장성이다. 대부분의 사용자는 몇 개의 플래그만 쓰는 명령줄 도구로 소비하겠지만, 그 내부에는 히스토리 재작성 도구를 만들기 위한 파이썬 라이브러리가 들어 있다. 특수한 요구를 가진 사용자는 이를 활용해 완전히 새로운 재작성 도구를 빠르게 만들 수 있다. 이 확장성은 별도 프로세스를 포크하지 않아 성능을 해치지 않고, OS에 종속된 셸 명령을 요구하지 않아 사용자끼리 명령을 공유할 수 있으며, 해시·딕셔너리·리스트 같은 풍부한 자료구조와 셸에서는 부실하기 짝이 없는 문자열 처리 능력을 온전히 제공한다. 실제로 filter-branch식 동작을 재현한 filter-lamely, BFG를 재구현한 bfg-ish가 이 라이브러리 위에 얹혀 있고, 두 기존 도구의 명령을 filter-repo로 옮기는 대조표(cheat sheet)도 마련돼 있다.
세부 처리의 정교함도 실무에서 체감되는 부분이다. 커밋 메시지가 다른 커밋을 해시로 참조하고 있으면(가령 "this reverts commit …") 새 해시에 맞게 자동으로 고쳐 주고, refs/replace 참조를 통해 옛 커밋 ID로 새 저장소를 조회할 수 있는 매핑도 남긴다. 필터링 결과 비어 버린 커밋은 잘라내되, 처음부터 비어 있던 커밋은 버전 관리나 배포 목적으로 일부러 만든 것일 수 있어 보존한다. 부모가 잘려 나가 위상이 무너지는 병합 커밋도 원래부터 그런 형태였다면(--no-ff 병합처럼) 손대지 않고, 오직 필터링으로 인해 사소해진 경우만 정리한다. 다만 히스토리 재작성은 본질적으로 협업 중인 공유 저장소의 커밋 해시를 전부 바꿔 놓는 파괴적 작업이라는 점은 변하지 않는다. filter-repo가 신선한 클론을 강제하는 것도 이 위험을 전제한 결과이니, 팀 저장소에 적용하기 전에는 반드시 사전 공지와 재클론 계획을 세워 두는 편이 안전하다.