How to Rename a Git Branch (Local and Remote)

To rename the branch you're on, run git branch -m new-name; to rename a different branch, run git branch -m old-name new-name. If the branch is already on a remote, push the new name with git push -u origin new-name and delete the old one with git push origin --delete old-name, because Git has no remote rename.

git branch -m fix-typo fix/typo-in-header     # rename locally
git push -u origin fix/typo-in-header         # publish new name, set upstream
git push origin --delete fix-typo             # remove old name from remote

Output below comes from Git 2.45 in a throwaway repository, with the remote shown as github.com:alex/project.git.

Rename a local branch: git branch -m

The git-branch manual describes -m (--move) as "Move/rename a branch, together with its config and reflog." Two forms:

git branch -m new-name             # renames the current branch
git branch -m old-name new-name    # renames any branch, from anywhere

You don't have to be on the branch for the second form. Nothing happens to commits; only the name changes.

If the new name is taken, Git stops. Example output:

$ git branch -m fix/typo-in-header main
fatal: a branch named 'main' already exists

-M ("shortcut for --move --force") overwrites the existing branch. That throws away whatever the other branch pointed to, so check it first with git log main --oneline -5.

Why the remote still has the old name

Renaming locally doesn't touch the remote, and the renamed branch keeps tracking the old remote branch, because its config moved with it. Example output, straight after the rename:

$ git branch -vv
* fix/typo-in-header 63c8bb9 [origin/fix-typo] init

That bracket means git pull still fetches from fix-typo on the server. A plain git push refuses, because the names no longer match. Example output, first lines:

$ 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:fix-typo

The next two steps fix it.

Rename a remote branch: push the new, delete the old

Push the new name and set it as upstream in one step. The git-push manual says -u adds the tracking reference "for every branch that is up to date or successfully pushed". Example output:

$ git push -u origin fix/typo-in-header
To github.com:alex/project.git
 * [new branch]      fix/typo-in-header -> fix/typo-in-header
branch 'fix/typo-in-header' set up to track 'origin/fix/typo-in-header'.

Then delete the old name:

$ git push origin --delete fix-typo
To github.com:alex/project.git
 - [deleted]         fix-typo

Check the result:

$ git branch -vv
* fix/typo-in-header 63c8bb9 [origin/fix/typo-in-header] init

If you want to keep pushing to the old remote name for now (for example, a pull request is open on it), skip both pushes. Just be aware that your local and remote names differ.

Rename a branch on GitHub

For a branch that other people use, renaming on GitHub is gentler than delete-and-push. Per GitHub's docs: open the repository, open the branch dropdown and click View all branches, click the ⋯ menu next to the branch, choose Rename branch, type the new name and confirm.

What GitHub updates for you:

• URLs containing the old branch name redirect to the new one.
• Branch protection rules follow the rename.
• Open pull requests that target the branch as their base are retargeted.

What it doesn't: raw file URLs are not redirected, git pull against the old name fails, GitHub Actions workflows that reference the old name need editing, and a pull request whose head branch you renamed is closed.

Update other clones after a rename

Everyone else's clone still has the old name. GitHub gives these commands to run in each clone:

git branch -m OLD-BRANCH-NAME NEW-BRANCH-NAME
git fetch origin
git branch -u origin/NEW-BRANCH-NAME NEW-BRANCH-NAME
git remote set-head origin -a

The third line points the local branch at the renamed remote branch. The last line updates origin/HEAD, which matters when the default branch was renamed. To drop the leftover origin/OLD-BRANCH-NAME entry, run git remote prune origin (or git fetch --prune).

Rename master to main

The default branch needs one extra step: a remote refuses to delete the branch that is currently its default (for a plain Git server, the message says this is denied "by default"). In a local test, pushing the delete before switching the default fails like this (example output, trimmed):

remote: error: refusing to delete the current branch: refs/heads/master
 ! [remote rejected] master (deletion of the current branch prohibited)

On GitHub the simplest route is the web rename above, which works on the default branch too. From the command line, the order is:

1. git branch -m master main
2. git push -u origin main
3. On GitHub: Settings, under Default branch click the switch icon, select main, click Update and confirm.
4. git push origin --delete master
5. git remote set-head origin -a, which prints origin/HEAD set to main.

Then update anything that names the old branch: CI configuration, deploy scripts, branch protection, and README badges.

To make future repositories start on main, set git config --global init.defaultBranch main. The git-init manual notes the built-in default is "currently master, but this will change to main when Git 3.0 is released".

Common mistakes

If the rename didn't stick

Run git branch -vv and git ls-remote --heads origin. The first shows your local names and what each tracks; the second shows what really exists on the server. If they disagree, repeat the push and delete steps above. If you'd rather remove a branch than rename it, see how to delete a Git branch, and if you are tidying history before a merge, merge vs rebase explains the trade-off.

Frequently asked questions

Does renaming a branch lose its commits or history?

No. A branch is a pointer to a commit, and git branch -m only changes the pointer's name. The commits, the branch's reflog and its configuration (such as its upstream) move with it. Nothing is rewritten.

Can I rename a remote branch directly?

Not with a single git command. Git has no remote rename, so you push the branch under the new name and delete the old name. GitHub, GitLab and similar hosts have a rename button in their web interface, and GitHub's version also redirects old URLs and retargets open pull requests.

What happens to an open pull request when I rename its branch?

It depends on how you rename. If you push a new name and delete the old one from the command line, GitHub sees the head branch disappear and the pull request is closed. If you rename the branch with GitHub's web interface, open pull requests that target it as their base are updated, but a pull request whose head branch you renamed is still closed, per GitHub's docs.

How do I make new repositories start on main instead of master?

Run git config --global init.defaultBranch main. From then on git init creates main as the first branch. For a single repository you can also use git init -b main.

Sources

• Git documentation: git-branch (-m, -M, --set-upstream-to)
• Git documentation: git-push (--delete, -u)
• Git documentation: git-init (init.defaultBranch)
• GitHub Docs: Renaming a branch
• GitHub Docs: Changing the default branch