In this tutorial I will share the steps and instructions to git rename branch (both local and remote).
My git version:
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:
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:
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:
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>
git branch -m <old_branch_name> <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
-m. It will raise an error saying that the branch already exists. You need to give unique name.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:
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
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:
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.
