Renaming a Git branch trips people up because “the branch” is really two things: the branch on your machine and the branch on the remote (GitHub, GitLab, etc.). To rename it properly you rename both, then point your local branch at the renamed remote one.

Here’s the whole thing first, then an explanation of each step.

TL;DR

# rename the branch you're currently on
git branch -m new-name

# push the new branch and set it as the upstream
git push origin -u new-name

# delete the old branch on the remote
git push origin --delete old-name

That covers the common case. Keep reading if you’re renaming a branch you’re not on, the default branch, or one other people are already using.

1. Rename the branch locally

If you’re on the branch you want to rename:

git branch -m new-name

If you’re on a different branch, give both the old and the new name:

git branch -m old-name new-name

-m stands for “move”. Use -M to force the rename if a branch with the new name already exists.

2. Push the new branch and delete the old one on the remote

The remote doesn’t know about the rename — to it, new-name looks like a brand-new branch while old-name still exists. Push the new one and set it as your upstream:

git push origin -u new-name

Then delete the old branch on the remote:

git push origin --delete old-name

You’ll often see the older syntax for the delete — git push origin :old-name does the same thing (pushing “nothing” to a branch deletes it).

3. Reset the upstream tracking

If you pushed with -u in the step above, your local branch already tracks the new remote branch and you can skip this. Otherwise, point it at the renamed remote branch yourself:

git branch -u origin/new-name

To clear out stale references to the branch you deleted:

git fetch --prune

Renaming the default branch (master → main)

Same idea, with one extra step — you can’t delete the default branch while it’s still the default, so change it in your host’s settings in the middle:

git branch -m master main
git push origin -u main

Now go to GitHub → Settings → Branches and set main as the default branch. Then delete the old one:

git push origin --delete master

If other people are working on the branch

Their local copies still point at the old name, so give them a heads-up. Anyone with work based on the old branch can move it across with:

git rebase --onto new-name old-name their-branch

And to make sure their Git picks up the renamed remote branches:

git remote set-branches origin '*'
git fetch

Verify

git branch -a

You should see the renamed branch both locally and under remotes/origin, with the old name gone. Done.

Found this useful, or got a case it doesn’t cover? Let me know.