How to Rename a Local Git Branch?

A branch is a simple pointer to a commit. The branch name must be relevant to the work performed on it. For example, the bugfix branch name suggests that some bug or error has been solved on that branch. We can use the git branch command to rename a branch. Let's learn how to rename a local branch in Git.

Renaming the Current Branch in Git

Use the git branch command with the -m flag to rename the currently checked-out branch.

git branch -m <new-branch-name>

For example, if we are on the master branch and want to rename it to main, we will run the following command.

git branch -m main

If we wish to rename a different branch, we can first check out that branch(using git checkout) and then use the above command. For example, if we are on the feature branch and want to rename the master branch to main, then we will run the commands shown below.

git checkout master # moving from feature to master branch
git branch -m main

Or we can use the code discussed in the next section.

Renaming a Branch from Another Branch in Git

We can rename a branch while checked-out on a different one by passing the current or existing branch name along with the new name.

git branch -m <exisiting-name> <new-name>

For example, if we are on the feature branch and want to rename the master branch to main, then we will run the following command.

git branch -m master main   # currently on feature branch

Duplicate Names in Git

By default, Git will block the renaming operation if the new branch name is not unique, i.e., the branch name already exists in our repository.

For example, consider we have a branch with the name bugfix. We will get an error if we rename the feature branch to bugfix.

git branch -m bugfix

Output

fatal: A branch named 'bugfix' already exists.

Use the -M flag to give a duplicate branch name.

git branch -M <new-branch-name>

Continuing the above example, we can use -M instead of -m to rename the feature branch to bugfix.

git branch -M bugfix

Note that the above command will rename your current branch. But the other branch with the same name will be deleted. Also, we may lose some commits. Branch names must be unique, and there can't be two branches with the same name.

For example, consider we have a repository with two branches(feature1 and feature2) and four commits(A, B, C, D).

A -- B -- C <- feature1
	 \
	  D	<- feature2

Now, if we rename the feature1 branch to feature2, then we will lose the commit D. Also, the original feature2 branch will be lost.

git branch -M feature2 	# currently on feature1 branch

A -- B -- C <- feature2

Resetting the Upstream Connection in Git

If the branch was pushed to the remote repository before renaming, then we need to delete that branch from the remote repository. Run the following Git Push command to delete the branch with the old name from the remote repo.

git push <remote-name> --delete <old-branch-name>

Next, we need to push the branch(using the new branch name) to the remote repo and set an upstream connection. Use the --set-upstream or -u option with the Git Push command to do so.

git push <remote-name> --set-upstream <new-branch-name>
git push <remote-name> -u <new-branch-name>

However, if you want the local branch(with the new name) to keep tracking the remote branch(with the old name), then use the following command. In this case, don't delete the remote branch using the git push <remote-name --delete <old-branch-name command.

git push --set-upstream <remote-name> <new-branch-name>:<old-branch-name>

Consider the following example to better understand the complete process.

Consider that we have a bugfix branch. This branch has been pushed to the remote repository. The remote name is origin. Now, we want to rename the bugfix branch to feature. Let's first rename it on our local repository.

git branch -m feature

Now, let's delete the branch called bugfix from the remote repository. Note that the remote repo still contains the old name, bugfix.

git push origin --delete bugfix

Finally, let's push the renamed branch(feature) to the remote repository. We will set an upstream connection using --set-upstream. It will help the future Git Push and Pull operations know which branch to work with. We will use the new name, feature, for this.

git push origin --set-upstream feature

Conclusion

Renaming local branches is pretty simple. We learned how to use the Git Branch command to rename a local branch. Git only allows unique names for branches. We can give a duplicate name to a branch, but this will delete the other branch. Use the git branch command to view the existing branch names.

It is also important to make relevant changes in the remote repository. We need to delete the branch with the old name from the remote repository and push the branch using the new name. This ensures that the remote repo is consistent with our local changes.