Git How to Rename a Branch (Locally & Remotely)

Renaming a git branch with git branch -m command

Did you typo the name of your Git branch? Do you think the branch deserves another name after your changes? Luckily, Git makes it easy to rename branches with a simple git branch -m command.

This is a comprehensive guide to renaming branches in Git. It teaches you how to rename a local branch in two different scenarios. Besides, you will learn how to push the newly named branch to the remote repo. Lastly, you will learn how to create a shorthand for renaming branches in the future.

All the theory is backed up by examples with a real repo.

Renaming a Local Git Branch

To rename the branch you’re currently working in, run the following command:

git branch -m <new-name>

To change the name of a branch you’re not checked, mention the name of the target branch followed by the new name:

git branch -m <target-branch> <new-name>

The -m option is shorthand for –move which means moving the branch to a new location with a new name.

Pushing the Renamed Local Branch

Once you’ve changed the name of your local branch, you can push it to the upstream and reset the upstream branch. This happens with the following command:

git push origin -u <new-name>

Where you replace the <new-name> with the new name of your branch.

This creates a new branch with a new name in the remote repository.

After pushing the newly named branch to the remote origin, you want to remove the original branch.

To do this, run the following command:

git push origin --delete <old-branch-name>

Where you replace the <old-branch-name> with the name of the original branch before renaming.

A Shorthand Trick to Renaming Branches

Using git branch -m to rename a branch isn’t big a hassle. But if you only have to do it every now and then, you will likely need to Google it over and over again.

Wouldn’t it be easier if you could do git rename instead of git branch -m?

To make this change, you can create a git rename alias for the git branch -m. When you do this, every time you do git rename, it calls git branch -m behind the scenes.

To create the alias, run the git config –global command as follows:

git config --global alias.rename 'branch -m'

After running this command, you can rename branches with git rename instead of git branch -m.

git rename my-branch my-cool-branch

Example

Let me show you a complete example that captures everything you learned today with a real Git repo.

Let’s start with a scenario where there is the main branch a feature branch called add-python-file in the remote repository.

main branch and add-python-file branch exist on the remote repo

These two branches also exist in the local repo. Let’s verify this by running git branch:

 $ git branch
  add-python-file
* main

Let’s check out the add-python-file branch:

 $ git checkout add-python-file

Then let’s change the name of the branch:

 $ git branch -m add-code-file

When we run this command, there will be no output. But we can check that the branch indeed changed by running the git branch command:

 $ git branch
* add-code-file
  main

At this point, we’ve only renamed the local branch. But because the remote branch also exists, we need to update it too. As you learned, we can push this newly named branch as a new branch to the remote origin and then delete the previous one.

Here’s the push:

 $ git push origin -u add-code-file
Total 0 (delta 0), reused 0 (delta 0)
remote: This repository moved. Please use the new location:
remote:   https://github.com/artturijalli/exampleProject.git
remote: 
remote: Create a pull request for 'add-code-file' on GitHub by visiting:
remote:      https://github.com/artturijalli/exampleProject/pull/new/add-code-file
remote: 
To https://github.com/artturijalli/exampleproject.git
 * [new branch]      add-code-file -> add-code-file
Branch 'add-code-file' set up to track remote branch 'add-code-file' from 'origin'.

Now let’s check what the remote looks like after the push:

Now both the newly named branch and the original branch exist on the remote origin. Naturally at this point, we want to delete the original one because we just changed the name.

 $ git push origin --delete add-python-file
remote: This repository moved. Please use the new location:
remote:   https://github.com/artturijalli/exampleProject.git
To https://github.com/artturijalli/exampleproject.git
 - [deleted]         add-python-file

Now the branch with the original name should be removed. Let’s check the origin once more:

Now there’s no trace of the add-python-file branch anymore. This indicates renaming the branch was successful!

Now, let’s create an alias for the git branch -m function so that we can call git rename instead:

$ git config --global alias.rename 'branch -m'

After running this command, let’s try to make it work. Let’s change the add-code-file back to add-python-file in the local repo:

$ git rename add-python-file

If the operation was successful, we should now be checked out in a branch called add-python-file. Let’s see if this is the case by using git branch:

 $ git branch
* add-python-file
  main

Success!

Thanks for reading. Happy coding!

Read Also