Merge pull request #1476 from HonkingGoose/feature/add-section-change-existing-branch-name

Author: ben

book/03-git-branching/sections/branch-management.asc

@@ -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
+----