From 3680ec78658a80690f2750ef50b5ec5188de8ffa Mon Sep 17 00:00:00 2001 From: HonkingGoose <34918129+HonkingGoose@users.noreply.github.com> Date: Sat, 8 Aug 2020 16:00:49 +0200 Subject: [PATCH 01/11] Create section: branch renaming --- .../sections/branch-management.asc | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/book/03-git-branching/sections/branch-management.asc b/book/03-git-branching/sections/branch-management.asc index a10789742..6554b83f1 100644 --- a/book/03-git-branching/sections/branch-management.asc +++ b/book/03-git-branching/sections/branch-management.asc @@ -73,3 +73,42 @@ $ git branch --no-merged master featureB ---- ==== + +==== Changing a branch name + +You can change a branch name with the `git branch -m` command. +If you want to collaborate with others, on the newly changed branch, you'll need to push it. + +[source,console] +---- +$ git branch -m bad-branch-name corrected-branch-name +$ git push -u origin 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. +Read the entire section before making any changes. +Do not attempt this move without first consulting with your co-workers. +Check beforehand where the old branch name is used in your project by doing a thorough search. +==== + +Changing the name from _master_ to _main_ can be done with the `git branch -m` command. +After changing the name, you'll need to push the renamed branch so that others can see it too. +Other users with a clone/fork of your repository will need to change their default branch as well. + +[source,console] +---- +$ git branch -m master main +$ git push -u origin main +---- + +Things to update after pushing the new default branch: +* Project dependency update helper configuration files. +* Test runner configuration files. +* Build scripts. +* Release scripts. +* Repository configuration settings (like the default branch that is targeted for pull-requests, branch-protection measures, etc). +* References to the old branch in documentation. From c6e58ba34b9ef38cf1a9e82d8bcb0f4c1c3fe643 Mon Sep 17 00:00:00 2001 From: HonkingGoose <34918129+HonkingGoose@users.noreply.github.com> Date: Mon, 10 Aug 2020 08:29:04 +0200 Subject: [PATCH 02/11] Apply suggestions from code review - Remove unnecessary comma - Explain what happens what the result is after changing your branch name and pushing the changed branch to the remote Co-authored-by: Ben Straub --- book/03-git-branching/sections/branch-management.asc | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/book/03-git-branching/sections/branch-management.asc b/book/03-git-branching/sections/branch-management.asc index 6554b83f1..d018e180c 100644 --- a/book/03-git-branching/sections/branch-management.asc +++ b/book/03-git-branching/sections/branch-management.asc @@ -77,7 +77,7 @@ $ git branch --no-merged master ==== Changing a branch name You can change a branch name with the `git branch -m` command. -If you want to collaborate with others, on the newly changed branch, you'll need to push it. +If you want to collaborate with others on the newly changed branch, you'll need to push it. [source,console] ---- @@ -105,7 +105,8 @@ $ git branch -m master main $ git push -u origin main ---- -Things to update after pushing the new default branch: +That changes the branch name in your repo, and makes the new name available in the remote. +Now you have a few more tasks in front of you to complete the transition: * Project dependency update helper configuration files. * Test runner configuration files. * Build scripts. From 9af27d49a0c241a3ac03582af037998af9c9d681 Mon Sep 17 00:00:00 2001 From: HonkingGoose <34918129+HonkingGoose@users.noreply.github.com> Date: Mon, 10 Aug 2020 14:15:59 +0200 Subject: [PATCH 03/11] Expand basic branch renaming section --- .../sections/branch-management.asc | 47 +++++++++++++++++-- 1 file changed, 43 insertions(+), 4 deletions(-) diff --git a/book/03-git-branching/sections/branch-management.asc b/book/03-git-branching/sections/branch-management.asc index d018e180c..93759f87e 100644 --- a/book/03-git-branching/sections/branch-management.asc +++ b/book/03-git-branching/sections/branch-management.asc @@ -76,13 +76,52 @@ $ git branch --no-merged master ==== Changing a branch name -You can change a branch name with the `git branch -m` command. -If you want to collaborate with others on the newly changed branch, you'll need to push it. +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 branch -m bad-branch-name corrected-branch-name -$ git push -u origin corrected-branch-name +$ git push origin --delete bad-branch-name +---- + +Now the bad branch name is fully replaced with the corrected branch name. + +[CAUTION] +---- +Do not delete branches that are still in use by other collaborators, or that are used in a pull request. ---- ===== Changing the master branch name From c5377f41877047854657be7121d25187c1c4a79b Mon Sep 17 00:00:00 2001 From: HonkingGoose <34918129+HonkingGoose@users.noreply.github.com> Date: Mon, 10 Aug 2020 14:16:37 +0200 Subject: [PATCH 04/11] Expand renaming master branch section --- .../sections/branch-management.asc | 34 +++++++++++++++---- 1 file changed, 28 insertions(+), 6 deletions(-) diff --git a/book/03-git-branching/sections/branch-management.asc b/book/03-git-branching/sections/branch-management.asc index 93759f87e..8fffaff55 100644 --- a/book/03-git-branching/sections/branch-management.asc +++ b/book/03-git-branching/sections/branch-management.asc @@ -134,17 +134,39 @@ Do not attempt this move without first consulting with your co-workers. Check beforehand where the old branch name is used in your project by doing a thorough search. ==== -Changing the name from _master_ to _main_ can be done with the `git branch -m` command. -After changing the name, you'll need to push the renamed branch so that others can see it too. -Other users with a clone/fork of your repository will need to change their default branch as well. +Rename your local _master_ branch into _main_ with the following command [source,console] ---- -$ git branch -m master main -$ git push -u origin main +$ git branch --move master main ---- -That changes the branch name in your repo, and makes the new name available in the remote. +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 of the repository: + +[source,console] +---- +git branch --all +* main + remotes/origin/HEAD -> origin/master + remotes/origin/main + remotes/origin/master +---- + +Your local _master_ branch is replace with the _main_ branch. +Your _main_ branch is also available on the remote. +The remote still has a _master_ branch. +Other collaborators will continue to use the _master_ branch until you make some further changes. + Now you have a few more tasks in front of you to complete the transition: * Project dependency update helper configuration files. * Test runner configuration files. From 557fbf11c0d675165ba60168e443f03a9df9e931 Mon Sep 17 00:00:00 2001 From: HonkingGoose <34918129+HonkingGoose@users.noreply.github.com> Date: Mon, 10 Aug 2020 14:23:32 +0200 Subject: [PATCH 05/11] Move caution to top of section - Warn about changing the mainline branch. --- book/03-git-branching/sections/branch-management.asc | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/book/03-git-branching/sections/branch-management.asc b/book/03-git-branching/sections/branch-management.asc index 8fffaff55..f7398d0a4 100644 --- a/book/03-git-branching/sections/branch-management.asc +++ b/book/03-git-branching/sections/branch-management.asc @@ -76,6 +76,12 @@ $ git branch --no-merged master ==== 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? @@ -119,11 +125,6 @@ $ git push origin --delete bad-branch-name Now the bad branch name is fully replaced with the corrected branch name. -[CAUTION] ----- -Do not delete branches that are still in use by other collaborators, or that are used in a pull request. ----- - ===== Changing the master branch name [WARNING] From ae00df22ffd1429f84cb753c66f7f076b6a0e084 Mon Sep 17 00:00:00 2001 From: HonkingGoose <34918129+HonkingGoose@users.noreply.github.com> Date: Mon, 10 Aug 2020 14:24:36 +0200 Subject: [PATCH 06/11] Use . instead of ? --- book/03-git-branching/sections/branch-management.asc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/03-git-branching/sections/branch-management.asc b/book/03-git-branching/sections/branch-management.asc index f7398d0a4..fdd7f44f9 100644 --- a/book/03-git-branching/sections/branch-management.asc +++ b/book/03-git-branching/sections/branch-management.asc @@ -82,7 +82,7 @@ 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? +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? From 6a6fb43294ffb90641d56197535be9c54dc07b09 Mon Sep 17 00:00:00 2001 From: HonkingGoose <34918129+HonkingGoose@users.noreply.github.com> Date: Mon, 10 Aug 2020 14:39:12 +0200 Subject: [PATCH 07/11] Refine text further --- book/03-git-branching/sections/branch-management.asc | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/book/03-git-branching/sections/branch-management.asc b/book/03-git-branching/sections/branch-management.asc index fdd7f44f9..44e39dc7f 100644 --- a/book/03-git-branching/sections/branch-management.asc +++ b/book/03-git-branching/sections/branch-management.asc @@ -152,7 +152,7 @@ This makes the renamed branch available on the remote. $ git push --set-upstream origin main ---- -Now we end up with the following state of the repository: +Now we end up with the following state:: [source,console] ---- @@ -163,10 +163,10 @@ git branch --all remotes/origin/master ---- -Your local _master_ branch is replace with the _main_ branch. -Your _main_ branch is also available on the remote. -The remote still has a _master_ branch. -Other collaborators will continue to use the _master_ branch until you make some further changes. +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: * Project dependency update helper configuration files. From a4dee159b0efb1389fb8aaf5272f6dbb14db9c06 Mon Sep 17 00:00:00 2001 From: HonkingGoose <34918129+HonkingGoose@users.noreply.github.com> Date: Mon, 10 Aug 2020 14:40:13 +0200 Subject: [PATCH 08/11] Expand master branch change section: - Add item to list - Explain how to remove the master branch --- book/03-git-branching/sections/branch-management.asc | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/book/03-git-branching/sections/branch-management.asc b/book/03-git-branching/sections/branch-management.asc index 44e39dc7f..6a5c9c569 100644 --- a/book/03-git-branching/sections/branch-management.asc +++ b/book/03-git-branching/sections/branch-management.asc @@ -175,3 +175,10 @@ Now you have a few more tasks in front of you to complete the transition: * Release scripts. * Repository configuration settings (like the default branch that is targeted for pull-requests, branch-protection measures, etc). * References to the old branch in documentation. +* Close/merge 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 +---- From ac555056c61d9c64c7a69c4000ddaf8d649980dd Mon Sep 17 00:00:00 2001 From: HonkingGoose <34918129+HonkingGoose@users.noreply.github.com> Date: Mon, 10 Aug 2020 15:08:28 +0200 Subject: [PATCH 09/11] Remove double : --- book/03-git-branching/sections/branch-management.asc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/03-git-branching/sections/branch-management.asc b/book/03-git-branching/sections/branch-management.asc index 6a5c9c569..7f33ee782 100644 --- a/book/03-git-branching/sections/branch-management.asc +++ b/book/03-git-branching/sections/branch-management.asc @@ -152,7 +152,7 @@ This makes the renamed branch available on the remote. $ git push --set-upstream origin main ---- -Now we end up with the following state:: +Now we end up with the following state: [source,console] ---- From 2d3e7bcc70a482f05e8f8aad145bf7b54f6346fb Mon Sep 17 00:00:00 2001 From: HonkingGoose <34918129+HonkingGoose@users.noreply.github.com> Date: Sun, 16 Aug 2020 09:02:45 +0200 Subject: [PATCH 10/11] Small flow improvement Co-authored-by: Ben Straub --- book/03-git-branching/sections/branch-management.asc | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/book/03-git-branching/sections/branch-management.asc b/book/03-git-branching/sections/branch-management.asc index 7f33ee782..454cb1e26 100644 --- a/book/03-git-branching/sections/branch-management.asc +++ b/book/03-git-branching/sections/branch-management.asc @@ -130,9 +130,8 @@ Now the bad branch name is fully replaced with the corrected 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. -Read the entire section before making any changes. -Do not attempt this move without first consulting with your co-workers. -Check beforehand where the old branch name is used in your project by doing a thorough search. +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 From 4d067c0c1050aece73c34ff54aedba7712a21640 Mon Sep 17 00:00:00 2001 From: HonkingGoose <34918129+HonkingGoose@users.noreply.github.com> Date: Sun, 16 Aug 2020 09:03:23 +0200 Subject: [PATCH 11/11] Improve text of bullet items Co-authored-by: Ben Straub --- .../03-git-branching/sections/branch-management.asc | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/book/03-git-branching/sections/branch-management.asc b/book/03-git-branching/sections/branch-management.asc index 454cb1e26..a15e010de 100644 --- a/book/03-git-branching/sections/branch-management.asc +++ b/book/03-git-branching/sections/branch-management.asc @@ -168,13 +168,12 @@ 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: -* Project dependency update helper configuration files. -* Test runner configuration files. -* Build scripts. -* Release scripts. -* Repository configuration settings (like the default branch that is targeted for pull-requests, branch-protection measures, etc). -* References to the old branch in documentation. -* Close/merge pull requests that target the old branch +* 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]