Introduction
Git is a tool for tracking software as it moves through stages of development. It uses branching to maintain a central repository of code while creating a copy to make changes on.
Sometimes, branch names become unclear as the project progresses, contain typos, or change purpose over time. Renaming branches can help maintain clarity and consistency with naming conventions, rectify any mistakes in the name, or reflect a change in the branch's purpose.
In this guide, learn how to change the name of a Git branch on a local system or remote repository.
Prerequisites
- A working Git installation (See how to install Git for Ubuntu, macOS, Windows, CentOS 7, or CentOS 8).
- Access to a terminal window/command line.
- A Git repository.
What Is a Branch in Git?
A Git branch represents a lightweight movable pointer to a commit. It acts as a label for a specific commit in the repository history that allows you to work on different features, fixes, or experiments within a project without affecting the main codebase.
Git branches allow you to manage different lines of development in a single project. They facilitate collaboration, experimentation, and organization of code changes. Using branches prevents unstable code from getting merged into the main code base and allows you to clean up your work before merging it into the master branch.
How to Rename a Git Branch
The process for renaming a Git branch depends on whether you are working with a local or a remote repository. Renaming a local branch involves using Git commands like git branch -m, while renaming a remote branch involves additional steps. This includes pushing the renamed branch and updating references on the remote server.
The sections below outline the steps for renaming both local and remote branches.
Rename Local Branch
A local Git branch is a branch within a Git repository that exists only on the local machine and is not shared with remote repositories. To rename a local branch, follow the steps below:
1. Open the terminal/command line and use the syntax below to switch to the branch you want to rename:
git switch [branch_name]For example:
2. Rename the branch using the syntax below:
git branch -m [new_branch_name]Replace [new_branch_name] with the name of the branch you want to use going forward.
Note: You can also change a local branch's name without switching to it. In that case, the syntax is:
git branch -m [old_branch_name] [new_branch_name]For example:
git branch -m bug-fixThe command renames the branch to the specified name.
3. Verify the renaming was successful by checking the status :
git branch -a 
The output confirms that the local branch was successfully renamed, as shown in the image above. However, the remote branch still retains its old name. Refer to the section below to see how to rename a remote Git branch.
Rename a Remote Git Branch
There is no direct way to rename a Git branch in a remote repository. You need to delete the branch with the old name and then push a branch with the correct name to the remote repository. Follow the steps below:
1. List the local branches to verify the local branch has the correct name:
git branch -a2. Next, delete the branch with the old name on the remote repository:
git push [remote_repository] --delete [old_branch_name]Replace [remote_repository] with the name of your remote repository and replace [old_branch_name] with the name of the branch you want to delete.
In the example below, we delete the branch bugs-fix from the origin remote repository:
Note: If you are using HTTPS for authentication, provide your user name and access token when prompted. For a more secure connection, use SSH. If you are not sure which one is better for you, read our article on SSH vs. HTTPS for Git.
3. Push the branch with the correct name and reset the upstream branch:
git push [remote_repository] -u [new_branch_name]
4. Verify that the branch has been renamed by listing the remote branches:
git branch -r
Conclusion
This guide has provided the steps on how to rename a local or remote Git branch and keep your repository clean and in check with your business' branch naming conventions.
Next, check out our Git beginner's guide and learn more about Git, or get acquainted with Git tags and learn how to use these reference points for marking version releases.
