[Savannah-cvs] [421] Change the instructions for git branch modifincations

[bob]

Revision: 421
          
http://svn.savannah.gnu.org/viewvc/?view=rev&root=administration&revision=421
Author:   rwp
Date:     2020-10-01 20:46:37 -0400 (Thu, 01 Oct 2020)
Log Message:
-----------
Change the instructions for git branch modifincations

Previously the instructions specified renaming branches.  But that had
the disadvantage of renaming the HEAD reference as well.  Instead
switch to making copies and safe non-forced deletions instead.  The
result is the same but these steps feel cleaner to me.

Modified Paths:
--------------
    trunk/sviki/Git.mdwn

Modified: trunk/sviki/Git.mdwn
===================================================================
--- trunk/sviki/Git.mdwn        2020-10-02 00:27:59 UTC (rev 420)
+++ trunk/sviki/Git.mdwn        2020-10-02 00:46:37 UTC (rev 421)
@@ -122,15 +122,18 @@
 Renaming a branch
 -----------------
 
-This needs some rationale and justification because during normal
-operation we never want to rewind a branch.  It causes problems for
-anyone who has pulled from the branch.  Normally branches only move
-forward.  But sometimes renaming a branch is the best solution to a
-problem.
+Renaming or deleting a branch needs some rationale and justification
+because during normal operation we never want to rewind a branch.
+Rewinding a branch causes problems for anyone who has pulled from the
+branch previously as it breaks being able to pull to it.  Normally
+branches only move forward.  But sometimes renaming a branch or
+deleting a branch is the best solution to a problem.  Use judgement.
 
-Sometimes a user has munged a commit, has pushed the desired branch onto
-a temporary branch (call it new-master), and wishes to have the new
-temporary branch become the master branch as the correction.
+Examples are that sometimes a user has munged a commit, has pushed the
+desired branch onto a temporary branch (call it new-master), and
+wishes to have the new temporary branch become the master branch as
+the correction.  If in your best judgement it should be modified then
+these are the steps that might be used to do it.
 
 Verify the current and future state of the repository:
 
@@ -138,18 +141,42 @@
     git branch -l
     git log
     git log new-master
+    git log --oneline --graph --decorate --color master new-master
 
-Move the current branch to master-broken as a backup save:
+Save the current branch to master-broken as a backup save.  Here I am
+calling it master-broken but use as descriptive of a name as
+appropriate.  Perhaps master-oldconversion for example.  Use your
+judgement.  This following creates master-broken based upon master.
 
-    git branch -m master master-broken
+    git branch master-broken master
 
-Move the new branch into place as master:
+Then now that the hash exists in another branch the easiest thing is
+to delete the master branch.  Use the lower case "-d" as that has a
+safety feature built into it which will warn and require a force
+option if this would remove the last reference to the objects.  But
+having a reference in master-broken that we just created this action
+will succeed without issue.
 
-    git branch -m new-master master
+    git branch -d master
 
-At this time the "current" branch will be shown to be master-broken:
+Then now that the name is available can do the same again and "create"
+a new branch named master based upon the desired branch.
 
+    git branch master new-master
+
+Verify the result.  The master branch should be the HEAD branch.  That
+is the default branch used with clients clone the repository.
+
     git branch -l
+    * master
+      master-broken
+
+Previous versions of these instructions specified to move the branches
+around.  That worked but also moved the HEAD as well and left HEAD
+referencing master-broken.  If you find yourself in this situation
+then the result will look like this following undesired state.
+
+    git branch -l
       master
     * master-broken
 
@@ -170,7 +197,10 @@
 
 Verify that the change is correct.  Better to leave the broken branch
 around for a while than to remove it too soon and lose something that
-should not have been lost.  Then clean up and discard the broken branch:
+should not have been lost.  I recommend being in no hurry to hard
+delete things.  Then clean up and discard the broken branch do the
+following.  This uses the "-D" which is a shortcut abbreviation for
+"--delete --force" and one should always be careful when using force.
 
     git branch -D master-broken