Changing the name of a Git branch is something you may need to do once in a while, and after mastering a few simple steps you can be an expert at it. However, changing branch names can cause conflicts if any of these steps are skipped. It is always best to avoid making project-wide changes unless absolutely necessary.
- Example Workflow For Changing a Branch Name
- Create a New Branch
- Push New Branch To Remote
- Change The Git Branch Name Locally
- Change The Git Branch Name on The Remote
Remember, when working with branches in Git you will have both local and remote branches. In this article, you will learn how to rename branches locally and then how to echo those changes to your remote server to avoid future conflicts.
For an ideal Git workflow, a fast VPS server gives you maximum speed, performance, and control over your hosting experience.
If you don’t need cPanel, don't pay for it. Only pay for what you need with our scalable Cloud VPS Hosting.
CentOS, Debian, or Ubuntu No Bloatware SSH and Root Access
Example Workflow For Changing a Branch Name
As a quick review, we will follow the full procedure for creating a new branch and making a commit. Then we will push the branch to the remote repository, change the name locally, and then change the name remotely to make sure they match.
To follow along with this example you will just need a test repository locally and a remote repository to push changes to. For the local project you can use any directory on your local workstation, for the remote you can use your VPS server. (For the purposes of this test it would be best if you have already been working in this project and already have some commits on the master branch.)
Create a New Branch
Start by creating a new branch. You can name this branch anything you want, but for this example the name “staging” will be used:
git checkout -b staging
You have now created a branch called “staging” and switched to it, because you used the “checkout” command. At this point, any changes you make to the project files will be committed on the “staging” branch.
git commit -am "<changes made>"
Push New Branch To Remote
So you have successfully created a local branch, but it is not present on the remote repository yet. In order to send it up to the remote you must do a Git push.
git push origin staging
Your branch is now present on the remote repository and in your local configuration. Now, you will proceed to changing the name of the branch locally.
Change The Git Branch Name Locally
Those of you familiar with the command line will recognize that you are not specifically “changing” the name so much as “moving it” in a similar fashion as the
mv command. The
git branch option you will be using is
--move for “move.” So, in effect, you are moving the old branch to the new branch (basically changing the name):
git branch -m <old branch> <new branch>
Try it out with the “staging” branch. For this example, you will change the name of the “staging” branch to “testing”:
git branch -m staging testing
Now, if you look at your branches with the
-a option you will notice a few things:
git branch -a
* testing remotes/origin/master remotes/origin/staging
git branch -a command shows you all of your local branches plus the references to remote branches. (Remember that each branch can spin off divergent branches, and sometimes you might want to push divergent branches to a different remote branch than master.)
Change The Git Branch Name on The Remote
In the above example you will note that you successfully changed the name of the “staging” branch to “testing” and the asterisk indicates you are still checking out that branch. But the remote path,
remote/origin/staging still says “staging” as the remote branch. This will definitely create confusion and conflicts. So in order to change the name remotely you will run this command:
git push origin :"<old branch>" "<new branch>"
Or, using the examples given:
git push origin :"staging" "testing"
And if you completed this part successfully you should see a message indicating what happened:
Total 0 (delta 0), reused 0 (delta 0) To example.com:/var/lib/git/project.git - [deleted] staging * [new branch] testing -> testing
This output indicates that the “staging” branch was deleted on the remote server and the new branch “testing” was created.
Both of these commands have updated the reference points, but to make these changes final, you must set “testing” as the upstream branch:
git push origin -u testing
And you will see a success message to indicate this was done correctly:
Branch 'testing' set up to track remote branch 'testing' from 'origin'.
Well done! You now know how to change the Git branch name locally and on the remote branch.