How to Rename a Local and Remote Git Branch

April 11, 2024

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.

tutorial on renaming or changing the name of a local and remote branch in git

Prerequisites

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:

Switching to a branch in Git before renaming it.

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

The command renames the branch to the specified name.

3. Verify the renaming was successful by checking the status :

git branch -a 
Renaming a local Git branch.

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

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

Deleting a branch from the 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]
Pushing a new branch name to a remote repository.

4. Verify that the branch has been renamed by listing the remote branches:

git branch -r
Listing remote branches in Git.

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.

Was this article helpful?
YesNo
Vladimir Kaplarevic
Vladimir is a resident Tech Writer at phoenixNAP. He has more than 7 years of experience in implementing e-commerce and online payment solutions with various global IT services providers. His articles aim to instill a passion for innovative technologies in others by providing practical advice and using an engaging writing style.
Next you should read
How To Switch Branch on Git
September 20, 2023

Developers need to switch between branches frequently. Git branches allow you to work on...
Read more
How to Install and Use Git on Windows
April 18, 2024

Git tracks source code changes during the software development process. It can help..
Read more
How to Create a New Branch in Git
January 9, 2024

This article outlines the basic commands needed to create a Git branch. A Git branch...
Read more
How To Install Git on Ubuntu 18.04 / 20.04
July 10, 2024

Git is a widely-used software package in Linux. Its main purpose is to track changes...
Read more