Skip to content

Create section: branch renaming #1476

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 13 commits into from
Aug 16, 2020
107 changes: 107 additions & 0 deletions book/03-git-branching/sections/branch-management.asc
Original file line number Diff line number Diff line change
Expand Up @@ -73,3 +73,110 @@ $ git branch --no-merged master
featureB
----
====

==== Changing a branch name

[CAUTION]
----
Do not rename branches that are still in use by other collaborators.
Do not rename a branch like master/main/mainline without having read the section "Changing the master branch name".
----

Suppose you have a branch that is called _bad-branch-name_ and you want to change it to _corrected-branch-name_, while keeping all history.
You also want to change the branch name on the remote (GitHub, GitLab, other server).
How do you do this?

Rename the branch locally with the `git branch --move` command:

[source, console]
----
$ git branch --move bad-branch-name corrected-branch-name
----

This replaces your bad-branch-name with corrected-branch-name, but this change is only local for now.
To let others see the corrected branch on the remote, push it:

[source,console]
----
$ git push --set-upstream origin corrected-branch-name
----

Now we'll take a brief look at where we are now:

[source, console]
----
$ git branch --all
* corrected-branch-name
main
remotes/origin/bad-branch-name
remotes/origin/corrected-branch-name
remotes/origin/main
----

Notice that you're on the branch corrected-branch-name.
The corrected branch is available on the remote.
However the bad branch is also still present on the remote.
You can delete the bad branch from the remote:

[source,console]
----
$ git push origin --delete bad-branch-name
----

Now the bad branch name is fully replaced with the corrected branch name.

===== Changing the master branch name

[WARNING]
====
Changing the name of a branch like master/main/mainline/default will break the integrations, services, helper utilities and build/release scripts that your repository uses.
Before you do this, make sure you consult with your collaborators.
Also make sure you do a thorough search through your repo and update any references to the old branch name in your code or scripts.
====

Rename your local _master_ branch into _main_ with the following command

[source,console]
----
$ git branch --move master main
----

There's no _master_ branch locally anymore, because it's renamed to the _main_ branch.

To let others see the new _main_ branch, you need to push it to the remote.
This makes the renamed branch available on the remote.

[source,console]
----
$ git push --set-upstream origin main
----

Now we end up with the following state:

[source,console]
----
git branch --all
* main
remotes/origin/HEAD -> origin/master
remotes/origin/main
remotes/origin/master
----

Your local _master_ branch is gone, as it's replaced with the _main_ branch.
The _main_ branch is also available on the remote.
But the remote still has a _master_ branch.
Other collaborators will continue to use the _master_ branch as the base of their work, until you make some further changes.

Now you have a few more tasks in front of you to complete the transition:
* Any projects that depend on this one will need to update their code and/or configuration.
* Update any test-runner configuration files.
* Adjust build and release scripts.
* Redirect settings on your repo host for things like thee repo's default branch, merge rules, and other things that match branch names.
* Update references to the old branch in documentation.
* Close or merge any pull requests that target the old branch.

After you've done all these tasks, and are certain the main branch performs just as the _master_ branch, you can delete the _master_ branch:
[source, console]
----
$ git push origin --delete master
----