빠른 흐름

git fetch --prune origin
git branch -r

# fetch 없이 stale remote-tracking refs만 정리
git remote prune origin

# 기본 fetch 때 자동 정리
git config --global fetch.prune true

정리 구조

stale branch는 실제 원격 브랜치가 아니라 오래된 remote-tracking ref다

원격 저장소에서 feature/old 브랜치가 삭제되어도 로컬의 origin/feature/old가 바로 사라지지는 않습니다. origin/feature/old는 마지막 fetch 시점의 원격 상태를 저장한 remote-tracking branch이기 때문입니다. 그래서 브랜치 목록에 남아 있다고 해서 실제 원격 브랜치가 아직 존재한다고 단정하면 안 됩니다.

git branch -r
git fetch --prune origin
git branch -r

git fetch --prune origin은 fetch를 수행하면서 원격에 더 이상 없는 remote-tracking refs를 정리합니다. 반면 git remote prune origin은 새 커밋을 가져오지 않고 stale remote-tracking refs만 정리합니다. 최신 커밋까지 함께 받고 싶으면 fetch --prune, 단순 청소만 필요하면 remote prune이 맞습니다.

prune은 refspec 기준으로 지운다

공식 문서 기준으로 prune은 "branch 전용 청소"가 아니라 remote의 refspec에 따라 로컬에 매핑된 ref를 지우는 기능입니다. 일반적인 remote branch refspec에서는 원격에서 사라진 branch 추적 ref가 정리됩니다. 하지만 tag refspec까지 명시하면 로컬 tag가 삭제 대상이 될 수 있습니다.

git fetch origin --prune
git fetch origin --prune --prune-tags

--prune-tags는 원격에 없는 tag까지 정리하려는 명시적 선택입니다. 여러 remote에서 tag를 받는 저장소나 릴리스 tag를 로컬에서 따로 관리하는 저장소에서는 예상보다 큰 변경이 될 수 있으므로, tag 정리는 branch 정리보다 더 신중하게 다룹니다.

운영 기준

팀 저장소에서는 fetch.prune=true를 켜 두면 삭제된 PR 브랜치가 계속 목록에 남는 문제를 줄일 수 있습니다. 단, 자동화 스크립트가 origin/old-branch 같은 remote-tracking ref 이름에 의존한다면 prune 도입 전 해당 스크립트의 가정을 확인해야 합니다.

주의할 점

실패 예시
- `origin/feature/old`가 보인다는 이유로 원격 브랜치가 살아 있다고 판단함
- tag refspec까지 prune해 로컬 tag가 사라짐
- local branch와 remote-tracking branch를 혼동해 내 작업 브랜치가 삭제된 줄로 오해함