docs/howto: use main when talking about the main branch

dscho · dscho · commit 68317764849a · 2020-11-02T13:47:33.000+01:00
Technically, some of these documents are mere copies from the Git
mailing list. As such, one might argue that they should not be modified.
However, they were added with the intention of documenting certain
things, and therefore it makes sense to keep them up to date.

Note: this patch _still_ leaves out documents that talk about git.git's
own branches, as we did not rename `master` (at least for now).

Signed-off-by: Johannes Schindelin &lt;johannes.schindelin@gmx.de&gt;
diff --git a/Documentation/howto/keep-canonical-history-correct.txt b/Documentation/howto/keep-canonical-history-correct.txt
@@ -136,7 +136,7 @@ this:
 ------------
 		 C0--C1--C2     topic-c
 		/
-    ---o---o---A                master
+    ---o---o---A                main
 		\
 		 B0--B1--B2     topic-b
 ------------
@@ -146,26 +146,26 @@ so:
 
 ------------
     $ git clone $URL work && cd work
-    $ git checkout -b topic-b master
+    $ git checkout -b topic-b main
     $ ... work to create B0, B1 and B2 to complete one theme
-    $ git checkout -b topic-c master
+    $ git checkout -b topic-c main
     $ ... same for the theme of topic-c
 ------------
 
 And then
 
 ------------
-    $ git checkout master
+    $ git checkout main
     $ git pull --ff-only
 ------------
 
-would grab `X`, `Y` and `Z` from the upstream and advance your master
+would grab `X`, `Y` and `Z` from the upstream and advance your main
 branch:
 
 ------------
 		 C0--C1--C2     topic-c
 		/
-    ---o---o---A---X---Y---Z    master
+    ---o---o---A---X---Y---Z    main
 		\
 		 B0--B1--B2     topic-b
 ------------
@@ -194,10 +194,10 @@ topic-c, somebody again advanced the history in the central repository
 to put `W` on top of `Z`, and make your `git push` fail.
 
 In such a case, you would rewind to discard `M` and `N`, update the
-tip of your 'master' again and redo the two merges:
+tip of your 'main' again and redo the two merges:
 
 ------------
-    $ git reset --hard origin/master
+    $ git reset --hard origin/main
     $ git pull --ff-only
     $ git merge topic-b
     $ git merge topic-c
diff --git a/Documentation/howto/revert-a-faulty-merge.txt b/Documentation/howto/revert-a-faulty-merge.txt
@@ -14,14 +14,14 @@ How to revert a faulty merge
 
 Alan <alan@clueserver.org> said:
 
-    I have a master branch.  We have a branch off of that that some
+    I have a main branch.  We have a branch off of that that some
     developers are doing work on.  They claim it is ready. We merge it
-    into the master branch.  It breaks something so we revert the merge.
+    into the main branch.  It breaks something so we revert the merge.
     They make changes to the code.  they get it to a point where they say
     it is ok and we merge again.
 
     When examined, we find that code changes made before the revert are
-    not in the master branch, but code changes after are in the master
+    not in the main branch, but code changes after are in the main
     branch.
 
 and asked for help recovering from this situation.
diff --git a/Documentation/howto/revert-branch-rebase.txt b/Documentation/howto/revert-branch-rebase.txt
@@ -11,37 +11,37 @@ Message-ID: <7voe7g3uop.fsf@assigned-by-dhcp.cox.net>
 How to revert an existing commit
 ================================
 
-One of the changes I pulled into the 'master' branch turns out to
+One of the changes I pulled into the 'main' branch turns out to
 break building Git with GCC 2.95.  While they were well-intentioned
 portability fixes, keeping things working with gcc-2.95 was also
-important.  Here is what I did to revert the change in the 'master'
+important.  Here is what I did to revert the change in the 'main'
 branch and to adjust the 'seen' branch, using core Git tools and
 barebone Porcelain.
 
 First, prepare a throw-away branch in case I screw things up.
 
 ------------------------------------------------
-$ git checkout -b revert-c99 master
+$ git checkout -b revert-c99 main
 ------------------------------------------------
 
 Now I am on the 'revert-c99' branch.  Let's figure out which commit to
-revert.  I happen to know that the top of the 'master' branch is a
+revert.  I happen to know that the top of the 'main' branch is a
 merge, and its second parent (i.e. foreign commit I merged from) has
 the change I would want to undo.  Further I happen to know that that
 merge introduced 5 commits or so:
 
 ------------------------------------------------
-$ git show-branch --more=4 master master^2 | head
-* [master] Merge refs/heads/portable from http://www.cs.berkeley....
- ! [master^2] Replace C99 array initializers with code.
+$ git show-branch --more=4 main main^2 | head
+* [main] Merge refs/heads/portable from http://www.cs.berkeley....
+ ! [main^2] Replace C99 array initializers with code.
 --
--  [master] Merge refs/heads/portable from http://www.cs.berkeley....
-*+ [master^2] Replace C99 array initializers with code.
-*+ [master^2~1] Replace unsetenv() and setenv() with older putenv().
-*+ [master^2~2] Include sys/time.h in daemon.c.
-*+ [master^2~3] Fix ?: statements.
-*+ [master^2~4] Replace zero-length array decls with [].
-*  [master~1] tutorial note about git branch
+-  [main] Merge refs/heads/portable from http://www.cs.berkeley....
+*+ [main^2] Replace C99 array initializers with code.
+*+ [main^2~1] Replace unsetenv() and setenv() with older putenv().
+*+ [main^2~2] Include sys/time.h in daemon.c.
+*+ [main^2~3] Fix ?: statements.
+*+ [main^2~4] Replace zero-length array decls with [].
+*  [main~1] tutorial note about git branch
 ------------------------------------------------
 
 The '--more=4' above means "after we reach the merge base of refs,
@@ -51,15 +51,15 @@ git.git repository, so this would show everything on both branches
 since then.  I just limited the output to the first handful using
 'head'.
 
-Now I know 'master^2~4' (pronounce it as "find the second parent of
-the 'master', and then go four generations back following the first
+Now I know 'main^2~4' (pronounce it as "find the second parent of
+the 'main', and then go four generations back following the first
 parent") is the one I would want to revert.  Since I also want to say
 why I am reverting it, the '-n' flag is given to 'git revert'.  This
 prevents it from actually making a commit, and instead 'git revert'
 leaves the commit log message it wanted to use in '.msg' file:
 
 ------------------------------------------------
-$ git revert -n master^2~4
+$ git revert -n main^2~4
 $ cat .msg
 Revert "Replace zero-length array decls with []."
 
@@ -79,12 +79,12 @@ $ git commit -a -s ;# read .msg into the log,
 ------------------------------------------------
 
 I could have screwed up in any of the above steps, but in the worst
-case I could just have done 'git checkout master' to start over.
+case I could just have done 'git checkout main' to start over.
 Fortunately I did not have to; what I have in the current branch
-'revert-c99' is what I want.  So merge that back into 'master':
+'revert-c99' is what I want.  So merge that back into 'main':
 
 ------------------------------------------------
-$ git checkout master
+$ git checkout main
 $ git merge revert-c99 ;# this should be a fast-forward
 Updating from 10d781b9caa4f71495c7b34963bef137216f86a8 to e3a693c...
  cache.h        |    8 ++++----
@@ -96,10 +96,10 @@ Updating from 10d781b9caa4f71495c7b34963bef137216f86a8 to e3a693c...
 ------------------------------------------------
 
 There is no need to redo the test at this point.  We fast-forwarded
-and we know 'master' matches 'revert-c99' exactly.  In fact:
+and we know 'main' matches 'revert-c99' exactly.  In fact:
 
 ------------------------------------------------
-$ git diff master..revert-c99
+$ git diff main..revert-c99
 ------------------------------------------------
 
 says nothing.
@@ -109,7 +109,7 @@ Then we rebase the 'seen' branch as usual.
 ------------------------------------------------
 $ git checkout seen
 $ git tag seen-anchor seen
-$ git rebase master
+$ git rebase main
 * Applying: Redo "revert" using three-way merge machinery.
 First trying simple merge strategy to cherry-pick.
 * Applying: Remove git-apply-patch-script.
@@ -131,7 +131,7 @@ The temporary tag 'seen-anchor' is me just being careful, in case 'git
 rebase' screws up.  After this, I can do these for sanity check:
 
 ------------------------------------------------
-$ git diff seen-anchor..seen ;# make sure we got the master fix.
+$ git diff seen-anchor..seen ;# make sure we got the main fix.
 $ make CC=gcc-2.95 clean test ;# make sure it fixed the breakage.
 $ make clean test ;# make sure it did not cause other breakage.
 ------------------------------------------------
@@ -150,11 +150,11 @@ be some days off:
 
 ------------------------------------------------
 $ git checkout rc
-$ git pull . master
+$ git pull . main
 Packing 0 objects
 Unpacking 0 objects
 
-* commit-ish: e3a693c...	refs/heads/master from .
+* commit-ish: e3a693c...	refs/heads/main from .
 Trying to merge e3a693c... into 8c1f5f0... using 10d781b...
 Committed merge 7fb9b7262a1d1e0a47bbfdcbbcf50ce0635d3f8f
  cache.h        |    8 ++++----
@@ -168,10 +168,10 @@ Committed merge 7fb9b7262a1d1e0a47bbfdcbbcf50ce0635d3f8f
 And the final repository status looks like this:
 
 ------------------------------------------------
-$ git show-branch --more=1 master seen rc
-! [master] Revert "Replace zero-length array decls with []."
+$ git show-branch --more=1 main seen rc
+! [main] Revert "Replace zero-length array decls with []."
  ! [seen] git-repack: Add option to repack all objects.
-  * [rc] Merge refs/heads/master from .
+  * [rc] Merge refs/heads/main from .
 ---
  +  [seen] git-repack: Add option to repack all objects.
  +  [seen~1] More documentation updates.
@@ -180,8 +180,8 @@ $ git show-branch --more=1 master seen rc
  +  [seen~4] Document "git cherry-pick" and "git revert"
  +  [seen~5] Remove git-apply-patch-script.
  +  [seen~6] Redo "revert" using three-way merge machinery.
-  - [rc] Merge refs/heads/master from .
-++* [master] Revert "Replace zero-length array decls with []."
-  - [rc~1] Merge refs/heads/master from .
-... [master~1] Merge refs/heads/portable from http://www.cs.berkeley....
+  - [rc] Merge refs/heads/main from .
+++* [main] Revert "Replace zero-length array decls with []."
+  - [rc~1] Merge refs/heads/main from .
+... [main~1] Merge refs/heads/portable from http://www.cs.berkeley....
 ------------------------------------------------
diff --git a/Documentation/howto/separating-topic-branches.txt b/Documentation/howto/separating-topic-branches.txt
@@ -14,7 +14,7 @@ than HEAD] while rewriting messy development history.  For example, I
 start doing some work without knowing exactly where it leads, and end
 up with a history like this:
 
-            "master"
+            "main"
         o---o
              \                    "topic"
               o---o---o---o---o---o
@@ -25,35 +25,35 @@ And often, one topic component is larger than the other.  It may
 contain more than two topics.
 
 In order to rewrite this mess to be more manageable, I would first do
-"diff master..topic", to extract the changes into a single patch, start
+"diff main..topic", to extract the changes into a single patch, start
 picking pieces from it to get logically self-contained units, and
-start building on top of "master":
+start building on top of "main":
 
-        $ git diff master..topic >P.diff
-        $ git checkout -b topicA master
+        $ git diff main..topic >P.diff
+        $ git checkout -b topicA main
         ... pick and apply pieces from P.diff to build
         ... commits on topicA branch.
 
               o---o---o
              /        "topicA"
-        o---o"master"
+        o---o"main"
              \                    "topic"
               o---o---o---o---o---o
 
 Before doing each commit on "topicA" HEAD, I run "diff HEAD"
 before update-index the affected paths, or "diff --cached HEAD"
-after.  Also I would run "diff --cached master" to make sure
+after.  Also I would run "diff --cached main" to make sure
 that the changes are only the ones related to "topicA".  Usually
 I do this for smaller topics first.
 
 After that, I'd do the remainder of the original "topic", but
 for that, I do not start from the patchfile I extracted by
-comparing "master" and "topic" I used initially.  Still on
+comparing "main" and "topic" I used initially.  Still on
 "topicA", I extract "diff topic", and use it to rebuild the
 other topic:
 
         $ git diff -R topic >P.diff ;# --cached also would work fine
-        $ git checkout -b topicB master
+        $ git checkout -b topicB main
         ... pick and apply pieces from P.diff to build
         ... commits on topicB branch.
 
@@ -62,7 +62,7 @@ other topic:
               /
              /o---o---o
             |/        "topicA"
-        o---o"master"
+        o---o"main"
              \                    "topic"
               o---o---o---o---o---o
 
@@ -76,7 +76,7 @@ After I am done, I'd try a pretend-merge between "topicA" and
               /                   /
              /o---o---o----------'
             |/        "topicA"
-        o---o"master"
+        o---o"main"
              \                    "topic"
               o---o---o---o---o---o
 
@@ -91,4 +91,4 @@ for cruft.  Then I can finally clean things up:
               /
              /o---o---o
             |/        "topicA"
-        o---o"master"
+        o---o"main"
diff --git a/Documentation/howto/setup-git-server-over-http.txt b/Documentation/howto/setup-git-server-over-http.txt
@@ -214,7 +214,7 @@ To check whether all is OK, do:
 
    curl --netrc --location -v http://<username>@<servername>/my-new-repo.git/HEAD
 
-...this should give something like 'ref: refs/heads/master', which is
+...this should give something like 'ref: refs/heads/main', which is
 the content of the file HEAD on the server.
 
 Now, add the remote in your existing repository which contains the project
@@ -233,9 +233,9 @@ Step 4: make the initial push
 
 From your client repository, do
 
-   $ git push upload master
+   $ git push upload main
 
-This pushes branch 'master' (which is assumed to be the branch you
+This pushes branch 'main' (which is assumed to be the branch you
 want to export) to repository called 'upload', which we previously
 defined with git-config.
 
diff --git a/Documentation/howto/update-hook-example.txt b/Documentation/howto/update-hook-example.txt
@@ -21,7 +21,7 @@ section of the documentation:
            $GIT_DIR/hooks/update refname sha1-old sha1-new
 
     The refname parameter is relative to $GIT_DIR; e.g. for the
-    master head this is "refs/heads/master".  Two sha1 are the
+    main head this is "refs/heads/main".  Two sha1 are the
     object names for the refname before and after the update.  Note
     that the hook is called before the refname is updated, so either
     sha1-old is 0{40} (meaning there is no such ref yet), or it
@@ -178,7 +178,7 @@ This uses two files, $GIT_DIR/info/allowed-users and
 allowed-groups, to describe which heads can be pushed into by
 whom.  The format of each file would look like this:
 
-    refs/heads/master   junio
+    refs/heads/main     junio
     +refs/heads/seen    junio
     refs/heads/cogito$  pasky
     refs/heads/bw/.*    linus
@@ -187,6 +187,6 @@ whom.  The format of each file would look like this:
 
 With this, Linus can push or create "bw/penguin" or "bw/zebra"
 or "bw/panda" branches, Pasky can do only "cogito", and JC can
-do master and "seen" branches and make versioned tags.  And anybody
-can do tmp/blah branches. The '+' sign at the "seen" record means
+do main and seen branches and make versioned tags.  And anybody
+can do tmp/blah branches. The '+' sign at the seen record means
 that JC can make non-fast-forward pushes on it.
diff --git a/Documentation/howto/using-merge-subtree.txt b/Documentation/howto/using-merge-subtree.txt
@@ -25,23 +25,23 @@ What you want is the 'subtree' merge strategy, which helps you in such a
 situation.
 
 In this example, let's say you have the repository at `/path/to/B` (but
-it can be a URL as well, if you want). You want to merge the 'master'
+it can be a URL as well, if you want). You want to merge the 'main'
 branch of that repository to the `dir-B` subdirectory in your current
 branch.
 
 Here is the command sequence you need:
 
 ----------------
 $ git remote add -f Bproject /path/to/B <1>
-$ git merge -s ours --no-commit --allow-unrelated-histories Bproject/master <2>
-$ git read-tree --prefix=dir-B/ -u Bproject/master <3>
+$ git merge -s ours --no-commit --allow-unrelated-histories Bproject/main <2>
+$ git read-tree --prefix=dir-B/ -u Bproject/main <3>
 $ git commit -m "Merge B project as our subdirectory" <4>
 
-$ git pull -s subtree Bproject master <5>
+$ git pull -s subtree Bproject main <5>
 ----------------
 <1> name the other project "Bproject", and fetch.
 <2> prepare for the later step to record the result as a merge.
-<3> read "master" branch of Bproject to the subdirectory "dir-B".
+<3> read "main" branch of Bproject to the subdirectory "dir-B".
 <4> record the merge result.
 <5> maintain the result with subsequent merges using "subtree"
 
