Rename a branch you haven't pushed yet

If the branch exists only on your computer, use git branch -m to change its name. This command renames the branch you are currently on without affecting anything on a server.

First, switch to the branch you want to rename by typing git checkout branch-name. Then type git branch -m new-branch-name. Git will rename it immediately. You can verify the change by typing git branch, which lists all your local branches.

This approach works because the branch has not been pushed to a remote server yet — only your computer knows about it. No one else's work is affected, and there is nothing to clean up on a server.

Key Takeaways

  • Rename an unpushed branch with git branch -m new-name while you are on that branch.
  • Rename a pushed branch by deleting the old name on the server with git push origin --delete old-name, then pushing the new name with git push origin new-name.
  • After pushing a renamed branch, update your local tracking reference with git branch -m old-name new-name if Git does not do it automatically.
  • Tell other people on your team before you rename a branch that others are using, because they will need to update their local copies.

Rename a branch that is already on a server

If you have pushed the branch to a remote server (like GitHub or GitLab), you need to delete the old name on the server and push the new name. This takes two steps.

First, rename the branch on your computer using git branch -m old-name new-name. You do not need to be on that branch to use this form of the command. Then push the new name to the server by typing git push origin new-name. Finally, delete the old name on the server by typing git push origin --delete old-name.

After you do this, anyone else working on that branch will see that the old name no longer exists on the server. They will need to update their local copy by running git fetch, then switch to the new branch name or delete their local copy of the old name.

Update your local tracking branch if needed

When you rename a branch on the server, Git sometimes does not automatically update the connection between your local branch and the remote one. You may see a message saying your branch is tracking a branch that no longer exists.

To fix this, type git branch -u origin/new-name while you are on the renamed branch. This tells Git that your local branch should now track the new name on the server. You can check the connection by typing git branch -vv, which shows which remote branch each local branch is tracking.

Tell your team before renaming a shared branch

If other people are working on the branch you want to rename, they need to know about the change. When they next run git fetch, they will see that the old branch name no longer exists on the server, which can cause confusion.

Send a message to your team explaining the old name and the new name. Ask them to run git fetch, then delete their local copy of the old branch by typing git branch -d old-name. They can then check out the new branch name or update their local copy to track it.

If someone has uncommitted work on the old branch, they should commit or stash it before deleting the local branch. Once the branch is deleted locally, they can switch to the new name and continue working.

Undo a branch rename

If you rename a branch and immediately realize you made a mistake, you can undo it before pushing to the server. Type git branch -m wrong-name correct-name to rename it again.

If you have already pushed the wrong name to the server, you can still fix it. Rename the branch locally again, push the correct name, and delete the wrong name from the server using git push origin --delete wrong-name. Then notify your team of the correction.

Common mistakes when renaming branches

The most common mistake is forgetting to delete the old branch name from the server. This leaves two names pointing to the same commits, which confuses team members about which name to use. Always run git push origin --delete old-name after pushing the new name.

Another mistake is renaming a branch that other people are actively using without telling them first. They will continue working on the old name, which no longer exists on the server, and their next push will fail. Always communicate the change before you push it.

A third mistake is assuming Git will automatically update tracking references. Sometimes it does, sometimes it does not. After renaming a pushed branch, run git branch -vv to check that your local branch is still tracking the correct remote branch.

Frequently Asked Questions

Does renaming a branch lose any commits or history?

No. A branch name is just a label pointing to a commit. Renaming the branch does not change the commits themselves or their history. All the work remains intact under the new name.

What happens if I rename a branch with an open pull request?

The pull request will still work, but it will show the old branch name in the interface. After you merge or close the pull request, you can safely delete the old branch name from the server. Some platforms like GitHub will update the display automatically.

Can I rename the main or master branch?

Yes, but it requires extra steps because it is usually the default branch on the server. Rename it locally, push the new name, then go into your repository settings on the server and change the default branch to the new name. Then delete the old name.

What if someone else pushed to the old branch name after I renamed it?

This creates a new branch with the old name on the server. You will need to decide whether to keep both names or delete the new one. Communicate with your team about which name should be used going forward.