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

Commit Message

Yutaro Ohno Jan. 9, 2023, 10:47 a.m. UTC

From: Yutaro Ohno <[e-mail]>

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 <[e-mail]>
---
    doc: add "git switch -c" as another option on detached HEAD
    
    cc: Eric Sunshine [e-mail]

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 <[e-mail]>
      
       ## 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 <[e-mail]>
      
     @@ 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(-)


base-commit: a38d39a4c50d1275833aba54c4dbdfce9e2e9ca1

Comments

Eric Sunshine Jan. 9, 2023, 7:53 p.m. UTC | #1

On Mon, Jan 9, 2023 at 5:53 AM Yutaro Ohno via GitGitGadget
<[e-mail]> wrote:
> 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 <[e-mail]>
> ---
> diff --git 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`,
>  ------------
> -$ 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>
>  ------------

Thanks. This version looks good to me and addresses reviewer comments[1,2,3].

[1]: https://lore.kernel.org/git/[e-mail]/
[2]: https://lore.kernel.org/git/xmqqk01wusmz.fsf@gitster.g/
[3]: https://lore.kernel.org/git/[e-mail]/

Junio C Hamano Jan. 13, 2023, 5:58 p.m. UTC | #2

Eric Sunshine <[e-mail]> writes:

> Thanks. This version looks good to me and addresses reviewer comments[1,2,3].

Thanks, both.  Let's queue and merge it to 'next'.

Patch

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