How to Rename a Git Branch

Git is a distributed version control system that views data as a series of snapshots. This is in contrast to delta-based version control systems, such as Concurrent Version System (CVS) and Subversion. These view their data as a set of files, and the changes made to each file over time.

In Git, once a copy of the remote repository has been checked out, work can be done on the local copy. Changes can be committed whenever needed. When ready, simply push these changes to the remote repository.

What is a Git Branch?

Work in a branch in order to isolate changes made locally from changes that other team members are making on their own machines. A Git branch is basically a label for a single or series of commits, or changes, that are related. A commit contains a snapshot of saved code along with a link to the previous commit. The default branch name in Git is master, although many repositories use the name main instead.

Unlike CVS or Subversion, Git encourages the free creation of development branches. The idea is to work in them, and later merge them into project, version, QA, or production branches. While working in a local branch, there is little fear of incomplete and/or untested code winding up in a production build.

Why Rename a Git Branch?

It’s common to name a new Git branch with your initials (or git handle) along a date, number, or description. Once code in the branch is complete, the project committers may require that a pull request (PR) be submitted. This starts the process of having the code reviewed and merged.

However, committers need to know what the branch is intended to accomplish, so renaming the branch to summarize its purpose may be required. The pull request provides additional space to describe the code in more detail. Different projects may have different standards for branch names submitted in pull requests. The general best practice is for the name to be descriptive of the changes made.

Another reason to rename a Git branch would be if there’s an error in the original name. For example, in some projects the name of a branch is supposed to contain the number of the bug or issue being fixed. If the bug number is 1291 and you accidentally named the branch bugfix-1292, then you’d want to rename the branch to bugfix-1291.

How to Rename a Branch in Git

Steps to Rename the Local and Remote Branches

Branches in a local repository can be renamed from the command line using the git command. However, additional steps are needed to push the change into the remote origin repository.

1. Use the following command to display a list of local branches:

   git branch

   The current branch is shown with an asterisk (*):

     main
   * example-branch

2. Now use the -r flag to display a list of remote-tracking branches:

   git branch -r

   origin/main
   origin/example-branch

3. Create a new branch using the following command syntax git branch <new-branch>:

   git branch bugfix-1292

To rename this branch to bugfix-1291, either switch into the branch or use the long form of the git branch -m command.

1. Switch into the new branch using the following command syntax git checkout <branch-name>:

   git checkout bugfix-1292

2. Now rename the branch to bugfix-1291:

   git branch -m bugfix-1291

Alternatively, if not already in branch bugfix-1292, use the two-parameter rename command syntax git branch -m <old-name> <new-name>:

git branch -m bugfix-1292 bugfix-1291

1. When done, push the renamed branch to the remote repository:

   git push origin -u bugfix-1291

2. If the branch was previously pushed to the remote repository, the old branch name still exists, so delete it:

   git push origin --delete bugfix-1292

Conclusion

Git branches help isolate the changes you make to a project from changes others are making. This avoids having incomplete code released to production. There are several reasons to rename a branch, but most have to do with a project’s naming conventions and chosen best practices. You now know how to rename a local branch. This includes pushing a renamed branch to, and deleting an old branch name from a remote repository.

More Information

You may wish to consult the following resources for additional information on this topic. While these are provided in the hope that they will be useful, please note that we cannot vouch for the accuracy or timeliness of externally hosted materials.

• Career Karma: How to Rename a Git Branch
• Stack Overflow: How do I rename a local Git branch?
• TheServerSide: How to rename and change a Git branch name locally & remotely