How to With Git: Rename Branch

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.

In this guide, we’ll cover how to rename a local Git branch, as well as how to rename a remote Git branch, and even rename a remote Github branch.

These all will help keep your development flow nice, clean, and easy to manage down the road when coming back to a project.

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?

If you’re just looking for the command to rename a remote Git branch, this is it:

git push -u origin feature2:feature3

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 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.