Git maintenance 사용법

본문 중간의 쿠팡 추천 상품 구매시 쿠팡 파트너스에서 일정액의 수수료를 제공받습니다.

Git maintenance 사용법

git maintenance는 저장소 데이터를 정리하고 보조 인덱스를 갱신해서 다른 Git 명령의 대기 시간을 줄이기 위한 관리 명령이다. 2026년 7월 11일 확인 기준 git-scm.com의 git-maintenance 문서는 이 매뉴얼의 최신 버전을 2.54.0으로 표시한다.

실무에서 중요한 질문은 세 가지다. 지금 한 번만 정리할 것인지, 백그라운드 스케줄을 붙일 것인지, 그리고 gc 중심으로 갈지 incremental 전략으로 갈지다. 이 글은 Git 공식 문서를 기준으로 run, register, start, 주요 task, 자동 gc와의 관계를 정리한다.

Git maintenance는 언제 쓰면 될까?

Git 공식 문서는 git add나 git fetch 같은 일상 명령이 반응성을 우선하기 때문에, 전체 저장소를 최적화하는 작업은 별도로 다뤄야 한다고 설명한다. 그래서 저장소가 커졌거나 pack 파일과 loose object가 쌓였을 때, 또는 commit-graph와 prefetch 같은 보조 데이터를 주기적으로 갱신하고 싶을 때 git maintenance를 고려하면 된다.

특히 대형 저장소, 원격 fetch가 잦은 저장소, 여러 worktree를 쓰는 저장소에서는 수동 정리보다 정책을 명확히 두는 편이 낫다. 반대로 작은 개인 저장소라면 기본 자동 유지보수만으로 충분한 경우도 많다.

가장 기본적인 실행은 무엇일까?

가장 단순한 사용은 필요할 때 직접 한 번 실행하는 것이다. 공식 문서에 따르면 git maintenance run은 별도 --task를 주지 않으면 현재 활성화된 maintenance.<task>.enabled 설정을 기준으로 task를 실행한다. 기본 상태에서는 maintenance.gc.enabled만 true다.

git maintenance run

즉 설정을 건드리지 않았다면 수동 실행 한 번은 대체로 gc 중심 정리로 이해하면 된다. 특정 작업만 분리해서 돌리고 싶다면 --task=commit-graph, --task=prefetch처럼 명시할 수 있다.

start와 register는 무엇이 다를까?

register는 현재 저장소를 유지보수 대상 목록에 등록하고, 스케줄 기반 유지보수에 필요한 기본 설정을 만든다. 공식 문서 기준으로 이 과정에서 maintenance.repo에 저장소가 추가되고, 설정이 비어 있으면 maintenance.strategy=incremental이 적용된다.

start는 여기서 한 단계 더 나간다. register와 같은 설정을 한 뒤, 플랫폼별 스케줄러를 만들어 시간 단위로 git maintenance run --scheduled를 실행한다. Linux에서는 가능하면 systemd-timer, 아니면 crontab을 사용한다고 문서가 설명한다.

git maintenance register
git maintenance start

정리하면 수동 관리만 원하면 run, 스케줄 없이 등록만 하고 싶으면 register, 백그라운드 자동 실행까지 원하면 start가 맞다.

기본 전략은 어떻게 이해하면 될까?

공식 문서의 maintenance.strategy 설명을 보면 수동 유지보수의 기본 전략은 geometric, 스케줄 유지보수의 기본 전략은 none이다. 다만 register는 저장소를 등록할 때 비어 있는 경우 incremental 전략을 설정한다.

incremental 전략은 매번 무거운 gc를 돌리지 않고, 시간대별로 부담을 나눠서 실행하는 방식이다. 문서에 나온 기본 스케줄은 commit-graph와 prefetch를 hourly, loose-objects와 incremental-repack를 daily로 두는 구조다. 따라서 사용자가 체감하는 지연을 줄이고 싶다면 스케줄 유지보수에서는 이 전략이 더 현실적이다.

어떤 task를 알아두면 좋을까?

모든 task를 외울 필요는 없지만, 공식 문서 기준으로 자주 마주치는 항목은 역할이 분명하다.

• commit-graph: commit-graph 파일을 점진적으로 갱신해 로그 탐색과 merge-base 계산 같은 작업을 돕는다.
• prefetch: 원격 객체를 refs/prefetch/ 아래로 미리 받아 두어 이후 fetch를 가볍게 만든다.
• gc: 불필요한 파일을 정리하고 pack을 크게 재구성하는 전통적인 정리 작업이다.
• loose-objects: loose object를 pack으로 옮겨 저장소 조각화를 줄인다.
• incremental-repack: multi-pack-index를 활용해 작은 pack 여러 개를 점진적으로 합친다.
• pack-refs, reflog-expire, worktree-prune: ref, reflog, stale worktree 정리에 초점이 있다.

문서에는 중요한 주의점도 있다. gc가 나중 단계에서 정리할 loose object를 만들 수 있기 때문에 loose-objects와 gc를 동시에 활성화하는 것은 권장되지 않는다.

 

 

자동 gc와는 어떤 관계일까?

Git 공식 문서에 따르면 일반적인 porcelain 명령은 저장소가 충분히 커졌다고 판단되면 git gc --auto를 실행할 수 있다. git-gc 문서는 기본적으로 loose object가 약 6700개를 넘거나, keep 표시가 없는 pack 수가 50개를 넘으면 자동 정리가 트리거될 수 있다고 설명한다.

반면 git maintenance register는 현재 저장소에서 maintenance.auto=false를 설정해 foreground 자동 유지보수를 끈다. 배경 스케줄을 쓰는 저장소라면 사용자 명령 도중 갑자기 정리 작업이 끼어드는 상황을 줄이려는 의도다.

또한 git-maintenance 문서는 가능하면 git gc 대신 git maintenance run --task=gc를 사용하라고 권한다. 이유는 git maintenance run이 객체 데이터베이스 잠금을 고려해 설계됐고, 스케줄 작업과 충돌을 줄이기 때문이다.

--auto와 --schedule는 언제 쓰면 될까?

run --auto는 threshold가 충족될 때만 maintenance를 실행한다. 공식 문서 예시는 gc.auto와 gc.autoPackLimit 같은 기준을 언급한다. 그래서 CI 직후나 fetch 직후에 조건부 정리만 하고 싶을 때 맞다.

run --schedule는 각 task의 maintenance.<task>.schedule 및 maintenance.<task>.lastRun 값을 보고, 아직 실행 주기가 되지 않았다면 건너뛴다. 스케줄러가 이미 돌아가는 환경에서는 이 방식이 더 자연스럽다. 둘은 서로 호환되지 않는다.

실무에서는 어떤 선택이 무난할까?

작거나 단순한 저장소라면 별도 설정 없이 필요할 때 git maintenance run만 실행해도 충분하다. 팀 저장소가 크고 fetch 빈도가 높다면 git maintenance start로 배경 스케줄을 붙이고, incremental 전략을 기반으로 가는 편이 공식 문서의 설계 방향과도 맞다.

반대로 이미 사내 공용 스케줄러나 별도 운영 정책이 있다면 register만 쓰고 외부 스케줄에서 run --schedule 또는 특정 --task만 호출하는 구성이 더 통제하기 쉽다. 핵심은 무거운 gc를 모든 저장소에 같은 빈도로 강제하지 않는 것이다.

FAQ

Q. git maintenance start를 실행하면 매번 gc가 도나?

아니다. 공식 문서 기준으로 register가 기본으로 설정하는 incremental 전략은 scheduled task에서 gc를 비활성화하고, 대신 commit-graph, prefetch, loose-objects, incremental-repack 같은 작업을 주기별로 나눠 실행한다.

Q. 원격 브랜치가 prefetch 때문에 바로 바뀌나?

그렇지 않다. 공식 문서는 prefetch가 원격 추적 브랜치를 직접 움직이지 않도록 요청한 ref를 refs/prefetch/ 아래에 저장한다고 설명한다. 사용자가 직접 fetch하지 않았는데 원격 추적 브랜치가 바뀌는 동작을 피하려는 설계다.

Q. 이미 다른 스케줄러를 쓰고 있어도 start가 필요할까?

반드시 그렇지는 않다. 공식 문서도 고급 사용자는 직접 스케줄을 짤 수 있다고 설명한다. 다만 그 경우에도 객체 데이터베이스 잠금과 동시 실행 충돌 가능성, 그리고 git gc를 maintenance 스케줄과 혼용하지 않는 원칙은 그대로 지키는 편이 안전하다.

정리

git maintenance는 저장소 최적화를 하나의 정책으로 묶어 주는 Git 기본 도구다. 한 번 수동 정리할 때는 run, 대상만 등록할 때는 register, 백그라운드 실행까지 붙일 때는 start로 이해하면 된다.

대부분의 팀 저장소에서는 무거운 gc를 자주 직접 돌리기보다, 점진적 task를 스케줄링하는 방식이 더 무난하다. 저장소 크기와 fetch 빈도, worktree 사용 여부를 기준으로 어떤 task를 활성화할지 결정하면 된다.

참고 자료

• Git Documentation: git-maintenance
• Git Documentation: git-gc