Quick Links
Key Takeaways
To rename the current, local branch use "git branch -m new-name." To rename a local branch from inside another, use "git branch -m old-name new-name." To rename a remote branch, delete it with "git push origin --delete old-name", then push the renamed local branch with "git push origin -u new-name."
Branching is a trivial exercise in Git. Unfortunately, trivial tasks rarely get due attention, and mistakes happen. If you've misnamed a branch, it'll have to be renamed. Here's how to do that.
Why Branch Names Are Important in Git
Anything to do with branches in classic version control systems (VCSs) was a big deal. It required a coordinated understanding that a branch was being added or merged, and all of the people using that repository had to make sure they didn't do anything---or forget to do something---in order for the operation to proceed and succeed.
Operations involving branches were often very slow, too. There was a time penalty top using branches. Git was designed from the get-go to be different. Because it is a distributed version control system, every user has a copy of the full repository on their local machine.
Branching on your local machine doesn't affect anyone else unless you push the branch to a remote repository. And in Git, branch operations are designed to be as easy to use as they are fast to complete. Branching in Git is very cheap in computational terms. It is a trivial action inside the local repository.
In fact, developers are encouraged to branch, and to branch often. Branches are just another tool inside your VCS that you benefit from. Branches aren't big scary things in Git, they're one of its most used features.
But familiarity can lead to contempt. Or, at least, to a casual regard for branches. Branching might be quick and simple in Git, but you still need to be focused when you create a branch. It's easy to mistype a branch name, or type the wrong name, resulting in a badly-named branch.
If the branch is going to be pushed to the remote repository at some point, it needs be correctly spelled. If it isn't, it'll cause confusion when others try to use it.
List Branches in Git Before Renaming Them
Checking what the current branch names are is a good first step. The git branch command lists branches for us. You can see the branches in the local repository with this command:
git branch
The branches are listed for us. The current branch is highlighted in green, and with an asterisk.
To see the branches and their commits, you can use the show-branch command.
git show-branch
You can see the branches on the remote repository by including the -r (remote) option.
git branch -r
To see local and remote branches with one command, use the -a (all) option.
git branch -a
We have more local branches than we have remote branches. Branch "feature16" hasn't been pushed to the remote repository yet. That's just an aspect of normal operation, not a problem.
Our problem is branch "feature19" should have been named "feature18." So that's the mistake we're going to correct.
How to Rename a Local Branch in Git
There are two ways you can rename a branch locally. You can checkout the branch and rename it, or you can rename the branch while you're working in some other branch.
To rename the current branch, make sure you've checked out and are using the branch you want to rename. Then use the git branch command with the -m (move) option.
git checkout feature19
git branch -m feature18
We checked out the "feature19" branch and renamed it to "feature18." Let's see what our branches look like now.
git branch
Our branch now has the correct name in the local repository.
If you want to, you can rename a branch when you're working in another branch. Here's an example where we're working in the "master" branch.
git branch
The command we use is the same command as before, but we need to provide the current name for the branch we're renaming, as well as the new name we want it to have.
git branch -m feature19 feature18
git branch
Again, the branch in our local repository has been renamed with the correct name.
How to Rename a Remote Branch in Git
The remote repository still holds the branch with the old name. To rename a remote branch, we delete the old branch and push the new branch.
If other users use this branch and push commits to it, you should do a pull before you rename it locally. This ensures your local repository is up to date and that changes made by other users won't be lost. Pulling their changes back to your repository before you rename the branch locally, means those changes will be in the new branch when you push it back to the remote repository.
Let's take a look at the state of our branches. We'll use the -a (all) option to see both the local and the remote branches.
git branch -a
We need to delete "feature19" from the remote repository, and push "feature18" to the remote.
git push origin --delete feature19
You'll be prompted for the password for the remote repository. Once the deletion has taken place you'll see a confirmation message.
Now we'll push our new branch to the remote, and use the -u (set upstream) option
git push origin -u feature18
Again, you'll be prompted for your password for the remote. The new branch is pushed to the remote, and we're told that branch "feature18" is set up to track changes in our local copy of the branch.
Let's check once more what state our local and remote branches are in.
git branch -a
Our branch has been successfully renamed both locally and remotely, and the remote branch is tracking the changes in our local branch.
Renaming Branches Is Simple
With Git, renaming branches is simple. If you're the only person who uses a repository or branch that needs renaming, it is very simple.
If others share the branch, make sure you communicate to them that you're going to rename the branch, and that they should push any uncommitted work. When they've pushed, you can pull the branch, then rename your branch locally and remotely.