Git rename branch - local and remote (PROPERLY)

In this tutorial I will share the steps and instructions to git rename branch (both local and remote).

My git version:

Advertisement
deepak@ubuntu:~/git_examples$ git --version
git version 2.32.0

Let me clone a branch from my gitlab server to demonstrate this article:

$ git clone git@gitlab.com:golinuxcloud/git_examples.git

 

Git rename branch workflow

Following is the basic workflow to rename a branch locally and remotely:

## If you want to rename a branch while pointed to any branch, do:
git branch -m <old_branch_name> <new_branch_name>

## If you want to rename the current branch, you can do:
git branch -m <new_branch_name>

## Delete the remote branch:
git push origin --delete <old_branch_name>

## Push the local branch to remote and reset the upstream branch:
git push origin -u <new_branch_name>

Now we will explain these steps in the next sections with different examples and scenarios.

 

git rename local branch only

This section assumes that you have a local branch (which is not available on the remote git server) and you intend to rename this local branch only. I will create some local branch:

$ git branch issue-7843
$ git branch issue-5632
$ git branch issue-9538

Following are the list of branch available on my local workstation:

deepak@ubuntu:~/git_examples$ git branch --all
  issue-5632
  issue-7843
  issue-9538
* main
  remotes/origin/HEAD -> origin/main
  remotes/origin/main

So the issue-5632, issue-7843 and issue-9538 are my local branched and are not available on remote git server. Let us use issue-7843 branch for demonstration:

Advertisement
deepak@ubuntu:~/git_examples$ git switch issue-7843
Switched to branch 'issue-7843'
Your branch is up to date with 'origin/main'.

Following are the list of directories on my repository:
Git rename branch - local and remote (PROPERLY)

I will go ahead an upload some patch under bugfixes directory:

deepak@ubuntu:~/git_examples$ cd bugfixes/

deepak@ubuntu:~/git_examples/bugfixes$ touch patch-7843-1

deepak@ubuntu:~/git_examples/bugfixes$ git add patch-7843-1

Now we have added patch-7843-1 to our local repo:
Git rename branch - local and remote (PROPERLY)

As you can see, currently I am in issue-7843 branch:

deepak@ubuntu:~/git_examples/bugfixes$ git branch
  issue-5632
* issue-7843
  issue-9538
  main

The syntax to rename local branch is:

git branch -m <new_branch_name>

Let's now rename this local branch to issue-new-7843.

deepak@ubuntu:~/git_examples/bugfixes$ git branch -m issue-new-7843

Check your current branch, as you can see the issue-7843 branch is not there any more and is renamed to issue-new-7843 as expected:

deepak@ubuntu:~/git_examples/bugfixes$ git branch
  issue-5632
  issue-9538
* issue-new-7843
  main

Verify your uncommitted changes to make sure they are still there:
Git rename branch - local and remote (PROPERLY)

Since this branch is only locally available, if you push these changes then a new branch issue-new-7843 would be created on the remote server so you don't need to perform any further renaming for remote branch here.

 

git rename remote branch only

In this section we assume that you intend to rename remote repository only.

 

Scenario-1: When remote branch is also cloned locally

In this scenario we assume that the respective remote branch is also cloned locally wherein you wish to rename the remote branch only, leaving the local branch with the existing name.

deepak@ubuntu:~/git_examples/bugfixes$ git branch
  issue-5632
  issue-9538
* issue-new-7843
  main

In our previous example we had renamed our local git branch to issue-new-7843 but it was not pushed to git server. So let's push this to the remote server:

deepak@ubuntu:~/git_examples/bugfixes$ git push origin issue-new-7843
Total 0 (delta 0), reused 0 (delta 0), pack-reused 0
remote:
remote: To create a merge request for issue-new-7843, visit:
remote:   https://gitlab.com/golinuxcloud/git_examples/-/merge_requests/new?merge_request%5Bsource_branch%5D=issue-new-7843
remote:
To gitlab.com:golinuxcloud/git_examples.git
 * [new branch]      issue-new-7843 -> issue-new-7843

Verify the list of remote branches:

deepak@ubuntu:~/git_examples/bugfixes$ git branch --remotes
  origin/HEAD -> origin/main
  origin/issue-new-7843
  origin/main

So now issue-new-7843 exists in my local workstation as well as remote server.

Let us go ahead and rename this branch name on the remote server only. The syntax to be used:

git push <remote> <remote>/<old_name>:refs/heads/<new_name> :<old_name>

Here,
remote is obvious - e.g. origin, old and new are names of branches old and new respectively.
old_name: Existing branch name
new_name: New branch name

So, we will use this syntax to rename remote branch from issue-new-7843 to issue-7843 on our gitlab server:

deepak@ubuntu:~/git_examples/bugfixes$ git push origin origin/issue-new-7843:refs/heads/issue-7843 :issue-new-7843
Total 0 (delta 0), reused 0 (delta 0), pack-reused 0
remote:
remote: To create a merge request for issue-7843, visit:
remote:   https://gitlab.com/golinuxcloud/git_examples/-/merge_requests/new?merge_request%5Bsource_branch%5D=issue-7843
remote:
To gitlab.com:golinuxcloud/git_examples.git
 - [deleted]         issue-new-7843
 * [new branch]      origin/issue-new-7843 -> issue-7843
NOTE:

With this step your old branch will be deleted and a new branch will be created with the new name.

The remote branch has been renamed successfully while the local branch name is still the same:

deepak@ubuntu:~/git_examples/bugfixes$ git branch
  issue-5632
  issue-9538
* issue-new-7843
  main

 

Scenario-2: When remote branch is not cloned locally

In this scenario we assume that the remote branch you plan to rename is not cloned locally. For example I have a remote branch feature is is not cloned on my local workstation:

deepak@ubuntu:~/git_examples$ git branch
* main

I also have some un-merged changes in my main branch. This is just to make sure my changes are not lost while renaming the remote branch:

deepak@ubuntu:~/git_examples$ git status
On branch main
Your branch is up to date with 'origin/main'.

Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        new file:   templates/index.html

deepak@ubuntu:~/git_examples$ git commit -m "Added index.html template" -a
[main 20412c0] Added index.html template
 1 file changed, 0 insertions(+), 0 deletions(-)

Now let us rename the remote branch using the same syntax as we used earlier, we will rename feature branch to new-feature:

deepak@ubuntu:~/git_examples$ git push origin origin/feature:refs/heads/new-feature :feature
Total 0 (delta 0), reused 0 (delta 0), pack-reused 0
remote:
remote: To create a merge request for new-feature, visit:
remote:   https://gitlab.com/golinuxcloud/git_examples/-/merge_requests/new?merge_request%5Bsource_branch%5D=new-feature
remote:
To gitlab.com:golinuxcloud/git_examples.git
 - [deleted]         feature
 * [new branch]      origin/feature -> new-feature

So our remote branch has been successfully renamed:

deepak@ubuntu:~/git_examples$ git branch --remotes
  origin/HEAD -> origin/main
  origin/issue-7843
  origin/main
  origin/new-feature

Now we can also push our previously committed changes to the main branch without loosing any changes:

deepak@ubuntu:~/git_examples$ git push origin main
Enumerating objects: 5, done.
Counting objects: 100% (5/5), done.
Compressing objects: 100% (2/2), done.
Writing objects: 100% (4/4), 329 bytes | 329.00 KiB/s, done.
Total 4 (delta 1), reused 1 (delta 0), pack-reused 0
To gitlab.com:golinuxcloud/git_examples.git
   cf00196..20412c0  main -> main

As you can see our main branch is ahead of new-feature branch by one commit:

deepak@ubuntu:~/git_examples$ git log --oneline
20412c0 (HEAD -> main, origin/main, origin/HEAD) Added index.html template
cf00196 (origin/new-feature, origin/issue-7843, new-feature) Added patch-1
e126b0b Adding new group
5e04f57 Created new script to add groups
...

 

git rename branch both local and remote

Now let us rename a git branch in both local and remote repository. Let me pull another branch from my remote repository:

deepak@ubuntu:~/git_examples$ git pull origin issue-7843:issue-7843
From gitlab.com:golinuxcloud/git_examples
 * [new branch]      issue-7843 -> issue-7843

So currently I have the following list of branch on my local workstation:

deepak@ubuntu:~/git_examples$ git branch
  issue-7843
* main
  new-feature

In this example we will rename issue-7843 to new-issue-7843 in both local and remote repository.

 

Step-1: Checkout as different branch

This is an optional step and you may choose to ignore it. You can also rename a branch while working in the same branch.

deepak@ubuntu:~/git_examples$ git switch main

Check your current branch

deepak@ubuntu:~/git_examples$ git branch
  issue-7843
* main
  new-feature

 

Step-2: Rename local branch

If you are still in the same branch (i.e. you skipped the step-1 above):

$ git branch -m <new_branch_name>

OR you must use the following command by specifying both old and new branch name:

$ git branch -m <old_branch_name> <new_branch_name>

Since we are in a different branch we will execute the following command to perfom the rename:

deepak@ubuntu:~/git_examples$ git branch -m issue-7843 new-issue-7843

Verify the new branch name in your local repo:

deepak@ubuntu:~/git_examples$ git branch
* main
new-feature
new-issue-7843

 

Step-3: Delete the old-name remote branch and push the new-name local branch

Next we will delete the old branch from the remote repository and push the new branch to the remote repo using following syntax:

$ git push origin :<old_branch_name> <new_branch_name>

Let us convert this syntax into command:

deepak@ubuntu:~/git_examples$ git push origin :issue-7843 new-issue-7843
Total 0 (delta 0), reused 0 (delta 0), pack-reused 0
remote:
remote: To create a merge request for new-issue-7843, visit:
remote:   https://gitlab.com/golinuxcloud/git_examples/-/merge_requests/new?merge_request%5Bsource_branch%5D=new-issue-7843
remote:
To gitlab.com:golinuxcloud/git_examples.git
 - [deleted]         issue-7843
 * [new branch]      new-issue-7843 -> new-issue-7843

Verify the list of branch on local and remote repo:
Git rename branch - local and remote (PROPERLY)

 

Step-4: Reset the upstream branch for the new-name local branch

For every branch that is up to date or successfully pushed, add upstream (tracking) reference:

$ git push --set-upstream origin <new_branch_name>

Let us execute this command on our workstation:

deepak@ubuntu:~/git_examples$ git push --set-upstream origin new-issue-7843
Branch 'new-issue-7843' set up to track remote branch 'new-issue-7843' from 'origin'.
Everything up-to-date

And you are all set to use the new branch name.

 

Summary

In this tutorial we covered different examples to rename a git branch both locally and remotely. One can safely rename a branch with '-m' (move), but one has to be careful with '-M', because it forces the rename, even if there is an existing branch with the same name already. I have not covered any examples with -M as it can be destructive and will rename your branch, but you will lose the old branch with that name and those commits because branch names must be unique.

 

Further Readings

You can read more about git branch at official git branch documentation.

Didn't find what you were looking for? Perform a quick search across GoLinuxCloud

If my articles on GoLinuxCloud has helped you, kindly consider buying me a coffee as a token of appreciation.

Buy GoLinuxCloud a Coffee

For any other feedbacks or questions you can either use the comments section or contact me form.

Thank You for your support!!

Leave a Comment