Git fetch.prune 사용법

Git fetch.prune 사용법

git fetch --prune와 fetch.prune는 원격에서 이미 삭제된 브랜치에 대응하는 stale remote-tracking ref를 정리할 때 쓰는 설정이다. 2026년 6월 14일 기준 Git 공식 문서는 --prune가 fetch 전에 원격에 더 이상 존재하지 않는 remote-tracking reference를 제거한다고 설명한다.

실무에서 중요한 점은 이것이 로컬 브랜치를 지우는 기능이 아니라는 점이다. 기본 대상은 origin/feature-x 같은 remote-tracking ref이며, 태그는 기본 자동 추적만으로 받아온 경우 pruning 대상이 아니다. 이 글은 Git 공식 문서를 기준으로 git fetch --prune, fetch.prune, remote.<name>.prune, --prune-tags를 언제 구분해야 하는지 정리한다.

Git fetch.prune은 무엇을 정리할까?

Git 공식 문서의 PRUNING 설명에 따르면 Git은 기본적으로 데이터를 쉽게 버리지 않으며, 원격에서 이미 삭제된 브랜치에 대한 로컬 참조도 계속 남겨 둔다. --prune를 주면 이런 stale reference를 fetch 전에 정리한다.

여기서 정리 대상은 일반적으로 refs/remotes/origin/* 아래의 remote-tracking ref다. 따라서 git branch -a 결과가 실제 원격 상태보다 지저분해졌거나, 브랜치 churn이 많은 저장소에서 오래된 원격 브랜치 흔적이 계속 남는다면 pruning이 직접적인 해결책이다.

로컬 브랜치 삭제와는 왜 다를까?

git fetch --prune는 원격 추적 참조를 정리하는 동작이지, 사용자가 만든 로컬 브랜치를 직접 지우는 명령이 아니다. 예를 들어 원격의 feature/login이 삭제되어도 로컬의 feature/login 브랜치는 그대로 남을 수 있다.

즉 "원격에는 없지만 내 작업 기록으로는 남겨 둘 로컬 브랜치"와 "원격 상태를 반영하기 위한 추적 참조"는 분리해서 봐야 한다. 이 차이를 이해하지 않으면 pruning을 과하게 위험한 기능으로 오해하기 쉽다.

한 번만 정리할 때와 항상 정리할 때는 어떻게 나눌까?

상황	권장 방법	이유
지금 한 번만 stale ref를 정리하고 싶다	git fetch --prune origin	명령 한 번에만 pruning을 적용할 수 있다.
대부분의 저장소에서 fetch마다 자동 정리하고 싶다	git config --global fetch.prune true	모든 fetch가 기본적으로 --prune처럼 동작한다.
특정 remote에만 적용하고 싶다	git config remote.origin.prune true	remote별로 정책을 다르게 둘 수 있다.

Git 공식 문서는 fetch.prune=true이면 fetch가 자동으로 --prune를 준 것처럼 동작한다고 설명한다. 동시에 remote.<name>.prune로 per-remote 설정도 둘 수 있으므로, 사내 mirror와 일반 origin의 성격이 다를 때 구분해서 쓰기 좋다.

git remote prune는 언제 쓰면 될까?

Git 공식 문서에서 git remote prune <name>은 stale reference를 삭제하지만 새 ref를 fetch하지 않는 명령으로 설명된다. 문서상 동작 의미는 git fetch --prune <name>와 가깝지만, 새로 받을 변경이 없다는 점이 차이다.

그래서 네트워크 fetch는 굳이 하지 않고 참조만 정리하고 싶을 때 git remote prune가 더 직접적이다. 변경 전 영향 범위를 보고 싶다면 git remote prune --dry-run origin으로 먼저 확인하는 편이 안전하다.

태그까지 같이 지워질 수 있다는 말은 무슨 뜻일까?

Git 공식 문서는 기본 자동 tag auto-follow나 --tags만으로 받아온 태그는 pruning 대상이 아니라고 설명한다. 하지만 explicit refspec으로 태그를 가져오거나 --prune-tags를 함께 쓰는 경우에는 로컬 태그도 pruning 대상이 될 수 있다.

문서가 특히 주의하라고 하는 지점도 여기다. refs/tags/*:refs/tags/* 같은 refspec은 여러 remote가 같은 로컬 태그 네임스페이스를 공유할 수 있으므로, 단순히 "원격 브랜치 정리"라고 생각하고 적용하면 예상보다 넓은 삭제가 일어날 수 있다.

fetch.pruneTags는 언제 켜는 편이 맞을까?

fetch.pruneTags=true는 pruning이 활성화된 fetch에서 tag refspec이 함께 적용되도록 만드는 설정이다. Git 공식 문서는 이 설정이 fetch.prune와 결합돼 upstream과 1:1 매핑을 유지하려는 경우에 유용하다고 설명한다.

다만 모든 저장소에 무조건 권장되는 기본값으로 보기는 어렵다. 로컬 전용 태그를 자주 만들거나, 여러 remote를 다루는 저장소라면 태그 정리는 브랜치 pruning보다 훨씬 보수적으로 봐야 한다.

실무에서는 어떤 기본값이 무난할까?

대부분의 일반적인 개발 저장소에서는 fetch.prune=true 정도가 무난한 기본값이다. 원격에서 이미 사라진 브랜치 참조를 계속 들고 있을 이유가 적고, git branch -a나 각종 브랜치 목록 기반 도구의 잡음을 줄이는 데 도움이 된다.

반면 fetch.pruneTags까지 기본 활성화할지는 태그 운영 정책을 확인한 뒤 결정하는 편이 낫다. 공식 문서도 tag pruning이 별도 refspec과 연결된 동작이라는 점을 분명히 설명하므로, 브랜치 pruning과 같은 위험도로 보면 안 된다.

FAQ

Q. git fetch --prune를 실행하면 내 로컬 브랜치도 같이 지워지나?

기본적으로는 아니다. Git 공식 문서 기준으로 pruning의 일반 대상은 원격에 더 이상 존재하지 않는 remote-tracking ref다.

Q. 자동화하고 싶으면 fetch.prune와 remote.origin.prune 중 무엇을 쓰면 될까?

대부분의 저장소에서 공통 정책을 쓰려면 fetch.prune가 단순하다. 특정 remote에만 다르게 적용해야 한다면 remote.<name>.prune가 더 정확하다.

Q. 태그도 항상 같이 정리하는 편이 좋나?

그렇게 단정하기는 어렵다. Git 공식 문서는 --prune-tags와 tag refspec이 로컬 태그 삭제로 이어질 수 있다고 설명하므로, 로컬 전용 태그가 있는 저장소라면 먼저 정책을 확인해야 한다.

정리

git fetch --prune의 핵심은 "원격에 없는 remote-tracking ref를 fetch 과정에서 정리한다"는 데 있다. 일회성 정리는 git fetch --prune origin, 지속적 자동화는 fetch.prune, remote별 제어는 remote.<name>.prune, 태그까지 1:1 동기화를 원할 때만 --prune-tags 또는 fetch.pruneTags를 검토하면 된다.

운영 기준을 한 줄로 줄이면 이렇다. 브랜치 pruning은 대체로 기본값 후보가 될 수 있지만, tag pruning은 저장소의 태그 소유권과 refspec 구조를 확인한 뒤 켜는 편이 안전하다.

참고 자료

• Git Documentation: git-fetch
• Git Documentation: git-config
• Git Documentation: git-remote