The fastest way to rename a branch

To rename the branch you are currently on, run git branch -m new-branch-name. If you want to rename a different branch without switching to it first, use git branch -m old-branch-name new-branch-name. The -m flag stands for "move", which is how Git treats a rename internally.

If the new name already exists, Git will refuse the rename and tell you so. If you want to overwrite an existing branch name anyway, use -M (capital M) instead of -m, though this is rarely necessary.

This command only changes the name on your local machine. If the branch exists on a remote server — such as GitHub, GitLab, or Bitbucket — you will need to follow the steps in the next section to update it there as well.

Key Takeaways

  • Rename a branch you are on with git branch -m new-name, or rename any branch with git branch -m old-name new-name.
  • After renaming locally, delete the old branch name on the remote with git push origin --delete old-name and push the new one with git push origin new-name.
  • If others are working on the old branch, tell them to run git branch -m old-name new-name and git pull to update their local copies.
  • Renaming the default branch (usually main or master) requires an extra step in your repository settings on the hosting platform.

Pushing the renamed branch to a remote server

After you rename a branch locally, the old name still exists on the remote. You need to delete it there and push the new name. First, delete the old branch on the remote by running git push origin --delete old-branch-name. Then push the new branch with git push origin new-branch-name.

If this is the first time you are pushing the new branch name, Git may ask you to set the upstream branch. Follow the command it suggests, which will look like git push --set-upstream origin new-branch-name. After that, future pushes from this branch will work with just git push.

Check that the rename worked by running git branch -a to list all branches, both local and remote. You should see the new name under remotes/origin and the old name should be gone.

Updating the branch on other people's machines

If other people have cloned the repository or are working on the old branch, they need to update their local copies. They should run git branch -m old-branch-name new-branch-name to rename their local branch, then git pull to sync with the remote.

If they have uncommitted changes on the old branch, they should commit or stash them first. Running git stash will save changes temporarily, and they can retrieve them later with git stash pop after the rename is complete.

If someone has the old branch checked out when they try to pull, Git will tell them the branch no longer exists on the remote. They can switch to a different branch with git checkout main (or whatever your default branch is called), then run the rename and pull commands above.

Renaming the default branch

If you are renaming the default branch — the one that is checked out when someone first clones the repository — you need to change the setting on your hosting platform as well. On GitHub, go to Settings > Branches and change the default branch name in the dropdown. On GitLab, go to Settings > Repository and change it under Default Branch. Bitbucket has the same option under Repository Settings > Repository Details.

After you change the default branch in your platform's settings, anyone who clones the repository will get the new branch name. People who already have the repository cloned will still see the old default branch until they run git pull and manually switch to the new one.

Renaming the default branch does not automatically update any CI/CD pipelines, deployment scripts, or documentation that reference the old name. Search your repository for mentions of the old branch name and update them by hand.

Undoing a branch rename

If you renamed a branch by mistake, you can rename it back. Run git branch -m wrong-name correct-name locally, then delete the wrong name on the remote with git push origin --delete wrong-name and push the correct one with git push origin correct-name.

If you have already pushed the wrong name to the remote and other people have started using it, tell them to follow the steps in the "Updating the branch on other people's machines" section above. The sooner you fix it, the fewer people will be affected.

Common mistakes when renaming branches

The most common mistake is renaming the branch locally but forgetting to delete the old name on the remote. This leaves two branch names pointing to the same commits, which confuses team members about which one to use. Always run git push origin --delete old-name after renaming.

Another mistake is renaming a branch that someone else is currently working on without telling them. They will push to the old branch name, which still exists locally on their machine, and the remote will create a new branch with that name. The best practice is to announce the rename in your team chat or pull request before you do it, especially for shared branches.

A third mistake is renaming the default branch without updating the platform settings. This can cause confusion because new clones will get one branch name while existing clones still point to the old one. Always update the default branch setting on GitHub, GitLab, or Bitbucket after renaming.

Frequently Asked Questions

Can I rename a branch that has a pull request open?

Yes. The pull request will still work because it points to the commits, not the branch name. After you rename the branch and push it to the remote, the pull request will update automatically to show the new branch name. You do not need to close and reopen it.

What happens if I rename a branch and then someone pushes to the old name?

Git will create a new branch with the old name on the remote. You will then have two branches — the renamed one and the new one with the old name. Delete the unwanted one with git push origin --delete old-name and tell the person who pushed to use the new name instead.

Do I need to update my local tracking branch after renaming?

Git handles this automatically when you run git push origin --delete old-name and git push origin new-name. Your local branch will be connected to the new remote branch. If you see a warning about a stale remote-tracking branch, run git remote prune origin to clean it up.

Can I rename a branch that is protected or requires approval?

You can rename the branch locally and push it, but the old branch name may still be protected on the remote. Go to your repository settings on GitHub, GitLab, or Bitbucket and remove the protection from the old branch name, then add it to the new one if needed.