Subject: [PATCH v2] doc: add "git switch -c" as another option on detached HEAD

From: "Yutaro Ohno via GitGitGadget" <[email-masked]>
Date: Mon, 09 Jan 2023 10:47:17 +0000

From: Yutaro Ohno <[email-masked]>

In the "DETACHED HEAD" section in the git-checkout doc, it suggests
using "git checkout -b <branch-name>" to create a new branch on the
detached head.

On the other hand, when you checkout a commit that is not at the tip of
any named branch (e.g., when you checkout a tag), git suggests using
"git switch -c <branch-name>".

Add "git switch -c" as another option and mitigate this inconsistency.

Signed-off-by: Yutaro Ohno <[email-masked]>
---
    doc: add "git switch -c" as another option on detached HEAD
    
    cc: Eric Sunshine [email-masked]

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1422%2Fohno418%2Fimprove-git-checkout-doc-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1422/ohno418/improve-git-checkout-doc-v2
Pull-Request: https://github.com/git/git/pull/1422

Range-diff vs v1:

 1:  b7a11452979 ! 1:  2103912b406 doc: use "git switch -c" rather than "git checkout -b" consistently
     @@ Metadata
      Author: Yutaro Ohno <[email-masked]>
      
       ## Commit message ##
     -    doc: use "git switch -c" rather than "git checkout -b" consistently
     +    doc: add "git switch -c" as another option on detached HEAD
      
          In the "DETACHED HEAD" section in the git-checkout doc, it suggests
          using "git checkout -b <branch-name>" to create a new branch on the
     @@ Commit message
          any named branch (e.g., when you checkout a tag), git suggests using
          "git switch -c <branch-name>".
      
     -    Use "git switch -c" and fix this inconsistency.
     +    Add "git switch -c" as another option and mitigate this inconsistency.
      
          Signed-off-by: Yutaro Ohno <[email-masked]>
      
     @@ Documentation/git-checkout.txt: before that happens. If we have not yet moved aw
      -$ git checkout -b foo   <1>
      -$ git branch foo        <2>
      -$ git tag foo           <3>
     -+$ git switch -c foo   <1>
     -+$ git branch foo      <2>
     -+$ git tag foo         <3>
     ++$ git checkout -b foo  # or "git switch -c foo"  <1>
     ++$ git branch foo                                 <2>
     ++$ git tag foo                                    <3>
       ------------
       
       <1> creates a new branch `foo`, which refers to commit `f`, and then

 Documentation/git-checkout.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 4cb9d555b4b..9f116acdbd6 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -477,9 +477,9 @@ before that happens. If we have not yet moved away from commit `f`,
 any of these will create a reference to it:
 
 ------------
-$ git checkout -b foo   <1>
-$ git branch foo        <2>
-$ git tag foo           <3>
+$ git checkout -b foo  # or "git switch -c foo"  <1>
+$ git branch foo                                 <2>
+$ git tag foo                                    <3>
 ------------
 
 <1> creates a new branch `foo`, which refers to commit `f`, and then

base-commit: a38d39a4c50d1275833aba54c4dbdfce9e2e9ca1
-- 
gitgitgadget