원격에서 지운 브랜치가 git branch -r에 계속 남아 있는 이유

문제 발생

PR이 머지되고 GitHub에서 브랜치가 삭제됐는데도 로컬에서는 계속 보였습니다.

$ git branch -r
  origin/main
  origin/feature/login      # 원격에는 없는 브랜치
  origin/feature/search     # 이것도

자동완성 후보가 계속 늘었고, 몇 달 전 사라진 브랜치를 체크아웃하려다 뒤늦게 알아채기도 했습니다.

원인 분석

git fetch는 새로 생긴 것을 가져올 뿐, 사라진 것을 지우지 않습니다. Git 문서가 이 설계를 그대로 설명합니다 — Git은 명시적으로 버려질 때까지 데이터를 유지하려는 기본 성향이 있으며, 이는 원격이 이미 삭제한 브랜치에 대한 로컬 참조를 계속 붙들고 있는 것으로도 이어집니다.

--prune 설명도 명확합니다 — fetch 전에, 원격에 더 이상 존재하지 않는 원격 추적 참조를 제거합니다.

이건 버그가 아니라 안전장치입니다. 상대 저장소가 잠깐 잘못된 상태여도 로컬 참조가 마음대로 사라지지 않습니다. 대신 정리는 사람이 요청해야 합니다.

해결 방안

1. 정리하며 가져옵니다.

git fetch --prune origin
git remote prune origin   # 가져오지 않고 정리만

2. 매번 기억하지 않도록 설정합니다. 문서가 안내하는 방법 그대로 — fetch.prune을 전역으로, 또는 원격별로 remote.<name>.prune을 둡니다.

git config --global fetch.prune true

3. 로컬 브랜치는 자동으로 사라지지 않습니다. 지워지는 건 origin/... 추적 참조뿐입니다. 남은 로컬 브랜치는 -vv로 드러납니다.

$ git branch -vv | grep ': gone]'
  feature/login  a1b2c3d [origin/feature/login: gone] 로그인 폼 정리

확인한 뒤 git branch -d로 지웁니다. -d는 머지되지 않은 브랜치를 거부하므로, 여기서 걸리면 정말 머지된 게 맞는지 먼저 봅니다.

4. --prune-tags는 따로 판단합니다. 문서가 경고하듯 이 옵션은 --prune과 달리 로컬에서 만든 태그까지 지울 수 있어 더 조심해서 써야 합니다. 습관적으로 붙이지 않습니다.

5. CI에서는 굳이 필요 없습니다. 매번 새로 클론하는 환경에는 낡은 참조 자체가 없습니다. 이건 오래 사는 개발 머신의 문제입니다.

공식 문서

• Git: git-fetch — --prune
• Git: git-branch