A good Git workflow should make use of branches for feature development, so you don’t clutter up your master branch with every change you make to your code. Learning how to rename a branch in Git can help keep your project history clean and easy to understand when it comes to figuring out when a new feature was introduced into your code.
These all will help keep your development flow nice, clean, and easy to manage down the road when coming back to a project.
Rename a Local Git Branch
To rename a local Git branch, we can use the Git branch -m command to modify the name:
$ git branch * feature1 master $ git branch -m feature1 feature2 $ git branch * feature2 master
That was easy, right?
Rename a Remote Git Branch
If you’re just looking for the command to rename a remote Git branch, this is it:
git push -u origin feature2:feature3
Full Example to Rename a Remote GitHub Branch
To explain renaming a remote Git branch, we’ll use a fictional GitHub project to show the process.
Clone a GitHub Repo
First, we clone the GitHub project to our local box with the Git clone command:
$ git clone https://github.com/myusername/myproject.git Cloning into 'myproject' ... remote: Counting objects: 3, done. remote: Total 3 (delta 0), reused 0 (delta 0) Unpacking objects: 100% (3/3) done. Checking connectivity... done.
Now our myproject repository was cloned from GitHub.
The Git remote command shows all tracked repositories we can pull from and push to:
$ git remote origin
In this case, we just see the default Git origin name for a remote server.
We can look more verbosely at this with the Git remote -v command and flag:
$ git remote -v origin https://github.com/myusername/myproject.git (fetch) origin https://github.com/myusername/myproject.git (push)
Push Local Git Branch to GitHub Repo
Now that you have a GitHub project downloaded locally, you can create a local branch:
$ git checkout -b feature2 Switched to a new branch 'feature2'
This is shorthand for:
$ git branch feature2 $ git checkout feature2 Switched to a new branch 'feature2'
After making changes, push “feature2” to the remote repository named “origin”:
$ echo "mychange" > newfile.txt $ git add newfile.txt $ git commit -m "newfile.txt added" [feature2 c9acad71 newfile.txt added 1 file changed, 1 insertion(+) create mode 100644 newfile.txt $ git push origin feature2 Total 3 (delta 0), reused 0 (delta 0) To https://github.com/myusername/myproject.git
Checkout a Remote Git Branch From a GitHub Repo
If the “feature2” branch just existed remotely on GitHub, you won’t be able to push it.
You can use the Git branch -a command to see all available local and remote branches:
$ git branch -a * master remotes/origin/HEAD -> origin/master remotes/origin/feature2 remotes/origin/master
You need to first check out the remote repository branch, give it a local name, and switch to it:
$ git checkout origin/feature2 -b feature2 Branch feature2 set up to track remote branch feature2 from origin Switched to a new branch 'feature2'
Rename Git Branch on Remote GitHub Repo
Now we can rename the remote branch to “feature3” and push it to the remote origin:
$ git push -u origin feature2:feature3 Total 0 (delta 0), reused 0 (delta 0) To https://github.com/myusername/myproject.git * [new branch] feature2 -> feature3 Branch feature2 set up to track remote branch feature 3 from origin.
We now linked our local “feature2” branch to the remote “feature3” branch.
Any changes in the “feature2” local branch will be pushed to “feature3.”
To fix this, we should also do a local Git branch rename like we did before:
$ git branch -m feature2 feature3 $ git branch * feature3 master
Delete Git Branch on Remote GitHub Repo
After renaming a remote branch, the old branch remains as well.
You can simply delete the old branch if you no longer need it:
$ git branch -a * feature3 master remotes/origin/HEAD -> origin/master remotes/origin/feature2 remotes/origin/feature3 remotes/origin/master $ git push origin :feature2 To https://github.com/myusername/myproject.git - [deleted] feature2 $ git branch -a * feature3 master remotes/origin/HEAD -> origin/master remotes/origin/feature3 remotes/origin/master
Tracking Issues With Git and Troubleshooting Them
Tracking issues arise from a lost “tracking reference” with a remote “repository:branch”.
These issues are indicated by Git using messages like the ones below when you try to push or pull code:
$ git push origin feature4 error: src refspec feature4 does not match any. error: failed to push some refs to https://github.com/myusername/myproject.git
This could happen if the remote branch was renamed to “feature4,” but the local wasn’t updated.
You can use the Git branch -a command to help see how to fix local vs remote branch issues.
Then you can use Git checkout and Git branch -u to correct the relationship.
Finally, rename the local branch to match the remote branch for simpler future management:
$ git branch -a feature3 * master remotes/origin/HEAD -> origin/master remotes/origin/feature3 remotes/origin/feature4 remotes/origin/master $ git checkout feature3 Switched to branch 'feature3' $ git branch -u origin/feature4 Branch feature3 set up to track remote branch feature4 from origin. $ git branch -m feature3 feature4 $ git branch * feature4 master $ git push origin feature4 To https://github.com/myusername/myproject.git 3cc5caa..5cedaff feature4 -> feature4
Hopefully you are now comfortable renaming Git branches either locally or remotely. Mastering the ability to use the Git branch rename functionality can save you a lot of development headaches down the road.