git 브랜치 이름 변경 — 로컬·원격과 안 될 때
로컬 브랜치 이름은 git branch -m 새이름 한 줄이면 바뀝니다. 문제는 원격에는 "이름 변경"이라는 동작이 없다는 점입니다. 옛 원격 브랜치를 지우고 새 이름으로 다시 올려야 하고, 이걸 빼먹으면 다음 git push에서 The upstream branch of your current branch does not match the name of your current branch가 뜹니다. 아래 명령과 출력은 git 2.43.0에서 임시 저장소와 원격을 만들어 직접 실행한 결과입니다.
1. 로컬 브랜치 이름 변경 — git branch -m
# ① 지금 체크아웃한 브랜치의 이름 바꾸기 (인자 1개)
git branch -m feature/bbb
# ② 다른 브랜치의 이름 바꾸기 (인자 2개 — 옛이름 새이름 순서)
git branch -m old-name new-name공식 문서의 설명이 정확합니다. -m은 "브랜치를 config와 reflog까지 함께 옮기거나 이름을 바꾼다"이고, "옛 브랜치에 reflog가 있었다면 새 이름에 맞게 이름이 바뀌고, 브랜치 이름 변경을 기억하기 위한 reflog 항목이 만들어진다"고 적혀 있습니다. "config까지 함께"가 뒤에서 문제가 되는 부분이니 기억해 두세요.
바뀌었는지는 -vv로 확인합니다. 대괄호 안이 그 브랜치가 따라가는 원격 브랜치(upstream)입니다.
$ git branch -vv
* feature/bbb 180aad5 [origin/feature/aaa] work
main 0f6b57c [origin/main] init로컬 이름은 feature/bbb로 바뀌었는데 upstream은 아직 origin/feature/aaa입니다. 이게 다음 장의 오류로 이어집니다.
2. 이름을 바꾼 뒤 push 하면 나는 오류
$ git push
fatal: The upstream branch of your current branch does not match
the name of your current branch. To push to the upstream branch
on the remote, use
git push origin HEAD:feature/aaa
To push to the branch of the same name on the remote, use
git push origin HEAD로컬 이름만 바꿨을 뿐 원격은 아직 옛 이름이라서 나는 오류입니다. 여기서 안내대로 git push origin HEAD를 그냥 치면 새 이름 브랜치가 하나 더 생기고 옛 브랜치도 그대로 남아 원격에 이름만 다른 브랜치 두 개가 공존하게 됩니다. 제대로 하려면 다음 장의 순서를 따르세요.
3. 원격 브랜치 이름 변경 — 3단계
깃에는 원격 브랜치의 이름을 바꾸는 명령이 없습니다. 지우고 다시 올리는 것이 정석입니다.
# 1) 로컬 이름 변경
git branch -m old-name new-name
# 2) 옛 원격 브랜치 삭제
git push origin --delete old-name
# 3) 새 이름으로 올리고 upstream 다시 연결
git push -u origin new-name실제로 실행하면 이렇게 나옵니다. 마지막 줄에서 upstream이 새 이름으로 다시 잡힌 걸 확인할 수 있습니다.
$ git push origin --delete feature/aaa
To ../remote.git
- [deleted] feature/aaa
$ git push -u origin feature/bbb
To ../remote.git
* [new branch] feature/bbb -> feature/bbb
branch 'feature/bbb' set up to track 'origin/feature/bbb'.
$ git branch -vv
* feature/bbb 6987c76 [origin/feature/bbb] moregit push origin :old-name도 --delete와 같은 뜻입니다.
4. 이미 있는 이름으로 바꾸려 할 때 — -m과 -M
$ git branch -m old-name keep-me
fatal: a branch named 'keep-me' already exists공식 문서는 "새 브랜치가 이미 존재하면 이름 변경을 강행하기 위해 -M을 써야 한다"고 하고, -M은 "--move --force의 축약"이라고 정의합니다.
-M은 원래 있던 브랜치를 조용히 덮어씁니다. 실행해 보면 기존 keep-me가 가리키던 커밋은 목록에서 사라지고, 새로 옮겨온 브랜치가 그 이름을 차지합니다. 확인 질문도, 경고 문구도 없습니다. 덮이는 쪽에만 있던 커밋이 있는지 먼저 보세요.
# 덮기 전에 keep-me 에만 있는 커밋 확인
git log main..keep-me --oneline
$ git branch -M old-name keep-me
$ git branch -vv
keep-me 3111d6f [origin/old-name] c2 # ← old-name 이 차지했고 옛 keep-me 는 사라짐
* main ce77e8a [origin/main] c1커밋 자체가 즉시 삭제되는 건 아니어서 git reflog에서 해시를 찾아 git branch 이름 해시로 되살릴 수는 있습니다. 다만 아무도 참조하지 않는 커밋은 나중에 정리(gc) 대상이 되니 믿고 있을 일은 아닙니다.
위 출력에서 하나 더 볼 것이 있습니다. 이름은 keep-me인데 upstream이 origin/old-name입니다. -m이 config를 함께 옮기기 때문인데, 설정을 직접 보면 이렇습니다.
$ git config --get-regexp '^branch\.'
branch.keep-me.remote origin
branch.keep-me.merge refs/heads/old-name그래서 이름을 바꾼 뒤에는 upstream을 반드시 다시 지정해야 합니다. 새로 push 할 때 -u를 붙이거나, 원격이 이미 정리돼 있다면 git branch -u origin/new-name으로 연결만 고칠 수 있습니다.
바꾸려는 브랜치를 지금 보고 있으면 -M도 거부됩니다
$ git branch -M old-name keep-me
fatal: cannot force update the branch 'keep-me' used by worktree at '/tmp/demo'덮이는 쪽 브랜치를 체크아웃해 둔 상태면 이 오류가 납니다. 다른 브랜치로 옮긴 뒤 다시 실행하세요. 작업 중인 변경 때문에 못 옮기겠다면 git stash 사용법으로 잠시 치워 두면 됩니다.
5. 팀원 쪽에서 해야 할 일
원격 브랜치 이름이 바뀌면 다른 팀원의 로컬은 아무것도 모릅니다. 그 사람이 그냥 git pull을 하면 이렇게 나옵니다.
$ git pull
* [new branch] new-name -> origin/new-name
Your configuration specifies to merge with the ref 'refs/heads/old-name'
from the remote, but no such ref was fetched.정리하는 순서는 이렇습니다. GitHub 공식 문서가 안내하는 절차와 같습니다.
git branch -m old-name new-name # 내 로컬 이름도 맞추고
git fetch origin --prune # 사라진 원격 추적 참조 정리
git branch -u origin/new-name # upstream 다시 연결
git remote set-head origin -a # origin/HEAD 갱신 (기본 브랜치가 바뀐 경우)--prune 전에는 없어진 원격이 gone으로 표시됩니다. 이 표시가 보이면 정리가 안 된 상태입니다.
$ git fetch --prune
- [deleted] (none) -> origin/old-name
$ git branch -vv
* old-name 99e0f8d [origin/old-name: gone] c26. 기본 브랜치(main)는 이 방법으로 안 됩니다
main처럼 원격의 기본 브랜치를 같은 순서로 바꾸려 하면 삭제 단계에서 거부됩니다.
$ git push origin --delete main
remote: error: By default, deleting the current branch is denied, because the next
remote: 'git clone' won't result in any file checked out, causing confusion.
remote: error: refusing to delete the current branch: refs/heads/main
! [remote rejected] main (deletion of the current branch prohibited)기본 브랜치를 지워 버리면 새로 clone 한 사람이 아무 파일도 체크아웃하지 못하기 때문입니다. 기본 브랜치는 호스팅 서비스의 설정 화면에서 바꿔야 합니다. 깃허브라면 저장소의 Settings → Branches에서 브랜치 이름 옆 변경 아이콘을 씁니다.
깃허브 UI로 바꾸면 명령줄로는 못 하는 것들이 함께 처리됩니다. 공식 문서에 따르면 "옛 브랜치 이름이 들어간 URL은 자동으로 새 이름 URL로 리디렉션"되고, "브랜치 보호 정책과 열려 있는 풀 리퀘스트(포크의 것 포함)의 base 브랜치, 초안 릴리스도 함께 갱신"됩니다.
git pull을 하는 경우에는 리디렉션하지 않는다", 그리고 "GitHub Actions 워크플로는 이름 변경을 따라가지 않으므로, 액션을 @옛브랜치이름으로 쓰던 사람은 깨진다"는 것입니다. CI 설정과 문서에 박힌 브랜치 이름은 따로 찾아 고쳐야 합니다.
자주 묻는 질문 (FAQ)
Q. 이름을 바꾸면 커밋 기록이 사라지나요?
아닙니다. 브랜치는 커밋을 가리키는 이름표라서, 이름만 바뀌고 커밋과 히스토리는 그대로입니다. reflog도 새 이름으로 함께 옮겨집니다.
Q. -m과 -M 중 뭘 써야 하나요?
평소에는 -m입니다. 같은 이름이 이미 있으면 -m이 막아 주는데, 이 거부가 안전장치입니다. -M은 덮이는 브랜치를 버려도 된다고 확인한 뒤에만 쓰세요.
Q. 이름을 바꿨는데 git push가 계속 옛 이름을 말합니다.
upstream 설정이 옛 원격 브랜치를 가리키고 있어서입니다. git branch -vv로 대괄호 안을 확인하고, git push -u origin 새이름 또는 git branch -u origin/새이름으로 다시 연결하세요.
Q. 원격 브랜치만 이름을 바꿀 수는 없나요?
없습니다. 깃은 원격 ref 이름 변경을 지원하지 않아 삭제 + 새로 push가 유일한 방법입니다. 기본 브랜치만 예외적으로 호스팅 서비스 설정에서 바꿉니다.
Q. 브랜치 이름을 바꿨더니 병합이 꼬였습니다.
이름 변경 자체는 히스토리를 건드리지 않으므로 원인은 다른 곳에 있습니다. 병합을 되돌리는 방법은 git merge 취소를 참고하세요.
마무리
정리하면 이렇습니다. ① 로컬은 git branch -m 새이름(현재 브랜치) 또는 git branch -m 옛이름 새이름. ② 원격에는 이름 변경이 없어서 --delete 후 push -u로 다시 올린다. ③ -m은 config까지 옮기므로 upstream이 옛 원격을 계속 가리킨다 — -vv로 확인하고 다시 연결한다. ④ -M은 기존 브랜치를 말없이 덮으니 덮이는 쪽을 먼저 확인한다. ⑤ 팀원은 fetch --prune + branch -u. ⑥ 기본 브랜치는 깃허브 설정 화면에서 바꾼다.
📚 참고 출처 (2026년 7월 29일 확인 · git 2.43.0 실행)
· Git 공식 문서 — git-branch
· GitHub Docs — Renaming a branch
COMMENTS