Gitlab Rename Branch

Gitlab Rename Branch

GitLab Rename Branch. It’s an easy process and it takes only a few minutes.

So let’s assume you’ve bought in: The master branch is not a great name for the default branch in your repository. Someone somewhere said you suggested “master” as in “master recording,” and you just worked with it. But now you know, it would gain a way more further reason for it to be called something similar “default” or “main” or “dev” or “release,”…but how do you make that change on GitLab?

GitLab doesn’t provide a specific feature that directly renames it in just one step. But, still an easy process.

Also, it’s worth highlighting that there is no rename function. The workaround’s to create a new branch from the one you would like to rename and delete the old one.

Some different scenarios and conditions will give us different ways to rename a branch on Gitlab. First, let’s see the requirements:

Regarding your branch that you need to rename:

1 – Is the branch the default one from your repository/project?

2 – Is this branch protected?

Depending on those two questions above, you may or may not rename it using the command line, and you need to use the web interface from GitLab to handle the branch.

Gitlab Rename Branch: No default and Not Protected

This scenario’s the most simple one. You can rename it on both approaches: Command-Line and Web Interface.

By command-line:

Begin by turning to the local branch, which you need to rename:

git checkout <old_branch_name>

Rename the local branch by executing:

git branch -m <new_branch_name>

Now, you have renamed the local branch.

In case if you already pushed the <old_branch_name> branch to the remote repository, perform the next steps to rename the remote branch.

Push the <new_branch_name> local branch and reset the upstream branch:

git push origin -u <new_branch_name>

Delete the <old_branch_name> remote branch:

git push origin --delete <old_branch_name>

Easy right? Now, let’s see the scenario where you need to perform some steps on Gitlab.

Gitlab Rename Branch: Rename Default Branch

To rename the default branch on Gitlab, you can start the process doing the same step above to copy the existing branch that would like to rename with a new name.

git branch -m <new_branch_name>
git push origin -u <new_branch_name>

If you try to delete a default branch, by command line:

git push origin --delete <old_branch_name>
remote: GitLab: The default branch of a project cannot be deleted.
 ! [remote rejected] temp2 (pre-receive hook declined)
error: failed to push some refs to '[email protected]:gitlab-rename-branch/devops-api.git'

So, we have to change the default branch using the web interface from Gitlab before deleting the current default branch.

Let’s see how to do it:

Go to the configuration page from your project, and then go to the repository section.

Gitlab Rename Branch - Repository Configuration
Gitlab Rename Branch – Repository Configuration

Select your new branch on the “Default Branch” list, then click on “Save Changes.”

Gitlab Rename Branch - Change the Default Branch
Gitlab Rename Branch – Change the Default Branch

Now you can delete the old branch using the command-line or using the Gitlab web interface. 

git push origin --delete <old_branch_name>

If you got an error message like this:

remote: GitLab: You can only delete protected branches using the web interface.
 ! [remote rejected] temp3 (pre-receive hook declined)
error: failed to push some refs to '[email protected]:/gitlab-rename-branch/devops-api.git'

If your old branch is protected, it is not possible to delete it from the command line. Instead, you need to delete it using Web Interface.

Gitlab Rename Branch - Delete Protected Branch
Gitlab Rename Branch – Delete Protected Branch


Branches are a portion of the software development process and one of the essential features of git. Branches are pointers to a particular commit.

Renaming a local Git Branch is a matter of running a single command. But, you can’t directly rename a remote branch; it’s required to push the renamed local branch and remove the branch with the old name.

If you would like to know more about branches on the official Gitlab Documentation.

Check also other articles related to Gitlab:

How to use the Gitlab CI Variables

Effective Cache Management with Maven Projects on Gitlab.

Pipeline to build Docker in Docker on Gitlab.

How to Autoscaling the Gitlab Runner.

How to execute Cloud Formation on Gitlab.

How to use Gitlab CI: Deploy to elastic beanstalk

Leave a Comment

Your email address will not be published.