How to rename a git branch

Renaming a branch in git is essentially: pick a new name locally, push it under that name to the remote, and delete the old name. The catch is that other clones of the repository still have the old name as their tracking branch, so a clean rename also involves telling them to update.

This guide walks through every variant you'll hit.

Rename the branch you're currently on

git branch -m new-name

-m (move) renames the current branch in place. No commits are changed, only the label.

Rename a different branch (without checking it out)

git branch -m old-name new-name

You don't need to be on old-name for this to work — but old-name must exist locally.

Push the rename to the remote

The rename above is local-only. To propagate to the remote:

git push origin -u new-name
git push origin --delete old-name

Order matters: push the new branch first, then delete the old one. If you delete first and the old branch is the one your CI / PR was tracking, you may break things temporarily.

A more concise form (one round trip):

git push origin :old-name new-name

The leading colon means "delete the remote branch named old-name" and the second arg pushes new-name.

Update the upstream tracking ref

After pushing, make sure the local branch tracks the new remote branch:

git branch -u origin/new-name

(-u was already passed in the git push -u above; this is for cases where you need to fix tracking later.)

Verify:

git branch -vv
# * new-name 1a2b3c4 [origin/new-name] commit message

On collaborators' clones

Other people who had old-name checked out will now see it as orphaned. Tell them to:

git fetch --prune origin               # fetch and forget deleted remote branches
git switch new-name                    # creates a local branch tracking origin/new-name
git branch -d old-name                 # delete the stale local branch

--prune (or git remote prune origin) is what removes the stale origin/old-name ref from their machine.

Rename the default branch (e.g. master → main)

The default branch needs an extra step because the remote has it set as HEAD. The full sequence on the server side:

# locally
git branch -m master main
git push -u origin main
git push origin --delete master      # only if the remote allows it; usually requires admin

Then on the hosting platform (GitHub / GitLab / Bitbucket / Gitea):

GitHub: Settings → Branches → change "Default branch" from master to main. After that the master branch can be deleted (or skip the delete step above and let the UI handle it).
GitLab: Settings → Repository → Default branch → set to main.
Bitbucket: Repository settings → Branching model → Main branch.

Open PRs targeting the old default need to be retargeted. Most platforms do this automatically when you change the default; check the open PR list afterwards.

Collaborators run:

git fetch origin
git branch -m master main
git branch -u origin/main main
git remote set-head origin -a

git remote set-head origin -a updates refs/remotes/origin/HEAD so things like git switch - and short refs resolve correctly.

Renaming with uncommitted changes

git branch -m doesn't touch your working tree, so it's safe with uncommitted changes. There is one edge case: if a branch with the new name already exists, the command fails. Force only if you're sure:

git branch -M new-name        # capital M: force, overwrites if new-name exists

-M is force-rename. It will silently clobber an existing branch with that name. Be careful.

Practical recipes

Quick local-only rename

git branch -m better-name

Rename and push in one go

git branch -m feature/login feature/auth-flow
git push origin -u feature/auth-flow
git push origin --delete feature/login

Fix a typo in a branch you just pushed

git branch -m feature/loign feature/login
git push origin :feature/loign feature/login
git branch -u origin/feature/login

Reset upstream after the remote was renamed by someone else

git fetch --prune origin
git branch -u origin/new-name

Pitfalls

CI / PR refs don't always follow renames. Open PRs and CI configs that hard-code the old branch name need updating. Check your CI YAML and any branch-protection rules.
git push --mirror will delete the new branch. If you push with --mirror, the remote is forced to match your local — but mirror pushes look at all refs, including remote-tracking ones. Don't use --mirror for normal renames.
Stale local branches. Other people's old-name will linger forever unless they git fetch --prune and git branch -d. Mention the rename in your PR / chat.
Branch protection rules on the hosting platform often reference branch names. Renaming develop may also need the protection rule renamed.

Summary

Local rename: git branch -m old-name new-name.
Push the new name, delete the old: git push origin :old-name new-name.
Re-establish tracking: git branch -u origin/new-name.
For default-branch renames, also change the default on the hosting platform and ask collaborators to update.
git fetch --prune is what drops stale origin/old-name from other machines.