Git Branch: How to rename a local and remote branch

You can rename a local or remote Git branch by using the -m command. While this is not a problem for the local branch, for the remote branch you must first delete the outdated version and replace it with the new one.

Git is a version control system that has been available license-free and free of charge since 2005. The special feature of the tool is that numerous de­velopers can work sim­ul­tan­eously and com­pletely autonom­ously on a project. This is because Git does not work with a central re­pos­it­ory, but each user can download a copy to his local computer. This also acts as a back-up. Git is char­ac­ter­ised by its ease of use and is quick to learn. In our Digital Guide you will find a Git tutorial, which will help you with the first steps when using the tool and ensure that you can soon start your own projects.

In order to un­der­stand how renaming the Git branch works, it is advisable to first take a look at how Git is actually struc­tured and used. The Git re­pos­it­ory is crucial in this regard. The version control system uses the re­pos­it­ory as a kind of col­lec­tion basin. All files of current and previous versions of a project are stored here and made available to all de­velopers. Any changes can thus be easily tracked, while errors can be corrected more quickly. In contrast to systems such as SVN Git builds thereby not on a central re­pos­it­ory, but on numerous local copies. Each developer can work on these in­de­pend­ently.

If a large number of de­velopers are working on a project and are pursuing different ap­proaches, it is all the more important to separate work steps and still maintain an overview. For this purpose, Git uses so-called branches. Think of it like a tree. Thus, numerous small branches or lines of de­vel­op­ment branch off from the large trunk of the entire project, which can be worked on autonom­ously. New features can be added with branches, or bugs can be fixed quickly. However, the original code is not changed.

There may be times when you need to rename a branch. This is because if the naming is wrong and other de­velopers continue to work with it, you may run into problems. For­tu­nately, despite the tight in­teg­ra­tion and various forks, if you want to rename a Git branch, it’s not a big issue. To do this, use the -m command. The cor­res­pond­ing syntax always follows the same structure:

‘git branch -m <old-name> <new-name>’.

However, there are dif­fer­ences between branches that you edit locally and those that are already remote. Below we explain the steps for both cases.

A local Git branch exists only on your computer. You make changes and tests here without other de­velopers noticing. Renaming it can therefore be done quickly.

1. In the command line, select the Git branch you want to rename. The command for this is ‘git checkout old-name’.
2. You will get a con­firm­a­tion that you have selected the correct branch. This will read ‘Switched to branch 'old-name'’.
3. Now perform the actual rename for the local Git branch. The ap­pro­pri­ate command for this is: ‘git branch -m new-name’.

Al­tern­at­ively, you have the option to rename the Git branch via the master. To do this, use the following steps:

1. Switch to the master via the command ‘git checkout master’.
2. Now enter the following command if you want to rename a branch: ‘git branch -m old-name new-name’.
3. To ensure that the rename was suc­cess­ful, retrieve the current status of the branch using the ‘git branch -a’ command.

In a remote re­pos­it­ory, you cannot simply rename a Git branch, as this would lead to com­plic­a­tions. Instead, you need to delete the old name and then add the branch with the new name. For­tu­nately, this is not too hard either and can be done with a few simple commands. As with the local branch, you have two options.

1. First, make sure the local branch has the correct, new name. The ap­pro­pri­ate command is ‘git branch -a’.
2. Now delete the branch with the old, incorrect name from the remote re­pos­it­ory. To do this, use the following command: ‘git push origin --delete old-name’.
3. Verify that the old branch has been deleted properly.
4. Now add the branch with the correct name. For this, use the command ‘git push origin -u new-name’.
5. Lastly, perform a reset of the upstream branch to ensure that the changes are effective.

However, if you want to rename the remote Git Branch with just one command, you also have the following option.

1. Enter the following command: ‘git push origin :old-name new-name’.
2. Then also perform a reset of the upstream branch as described above.

Mistakes happen, and Git is designed to let you rename Git branches easily. It can be done quickly and with a few commands. While the process is a rename in the true sense for local branches, a deletion is necessary in the remote branch. Once the error is fixed, it makes sense to carefully double-check. Af­ter­wards you and other de­velopers can continue working on your project without any re­stric­tions.