[PATCH] doc: use "git switch -c" rather than "git checkout -b" consistently

[PATCH] doc: use "git switch -c" rather than "git checkout -b" consistently

[Yutaro Ohno via GitGitGadget]

From: Yutaro Ohno <yutaro.ono.418@gmail.com>

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>".

Use "git switch -c" and fix this inconsistency.

Signed-off-by: Yutaro Ohno <yutaro.ono.418@gmail.com>
---
    doc: use "git switch -c" rather than "git checkout -b" consistently

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

 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..ba3d6164847 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 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: 2b4f5a4e4bb102ac8d967cea653ed753b608193c
-- 
gitgitgadget

Re: [PATCH] doc: use "git switch -c" rather than "git checkout -b" consistently

[Junio C Hamano]

"Yutaro Ohno via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Yutaro Ohno <yutaro.ono.418@gmail.com>
> Subject: Re: [PATCH] doc: use "git switch -c" rather than "git checkout -b" consistently

Hmph.  When two things work equally well, is it a good idea to
describe only one "consistently", or mention both that can be used
pretty much interchangeably in different places?  I am not 100% sure
"consistently" is a good thing here.

Thoughts from others?

Re: [PATCH] doc: use "git switch -c" rather than "git checkout -b" consistently

[Eric Sunshine]

On Sun, Jan 8, 2023 at 11:36 PM Junio C Hamano <gitster@pobox.com> wrote:
> > From: Yutaro Ohno <yutaro.ono.418@gmail.com>
> > Subject: Re: [PATCH] doc: use "git switch -c" rather than "git checkout -b" consistently
>
> Hmph.  When two things work equally well, is it a good idea to
> describe only one "consistently", or mention both that can be used
> pretty much interchangeably in different places?  I am not 100% sure
> "consistently" is a good thing here.
>
> Thoughts from others?

Perhaps if the patch was sold as filling in a gap left by 328c6cb853
(doc: promote "git switch", 2019-03-29) it would be more palatable.

It does feel a bit strange that within the git-checkout documentation,
this patch is replacing an example invocation of git-checkout with an
invocation of git-switch. However, as the list of commands the patch
touches is given merely as examples one might use, then I could see
git-switch being prepended to the list rather than entirely replacing
git-checkout. For instance:

    If we have not yet moved away from commit `f`,
    any of these will create a reference to it:

    ------------
    $ git switch -c foo     <1>
    $ git checkout -b foo   <1>
    $ git branch foo        <2>
    $ git tag foo           <3>
    ------------

Re: [PATCH] doc: use "git switch -c" rather than "git checkout -b" consistently

[Junio C Hamano]

Eric Sunshine <sunshine@sunshineco.com> writes:

> touches is given merely as examples one might use, then I could see
> git-switch being prepended to the list rather than entirely replacing
> git-checkout. For instance:
>
>     If we have not yet moved away from commit `f`,
>     any of these will create a reference to it:
>
>     ------------
>     $ git switch -c foo     <1>
>     $ git checkout -b foo   <1>
>     $ git branch foo        <2>
>     $ git tag foo           <3>
>     ------------

That can invite "do we need to use checkout after doing switch?"
confusion.  I would understand if it were

	$ git checkout -b foo # or "git switch -c foo" <1>

or something that makes it clear either one, but not both, is used
there.

Thanks.

Re: [PATCH] doc: use "git switch -c" rather than "git checkout -b" consistently

[Eric Sunshine]

On Mon, Jan 9, 2023 at 1:30 AM Junio C Hamano <gitster@pobox.com> wrote:
> Eric Sunshine <sunshine@sunshineco.com> writes:
> > touches is given merely as examples one might use, then I could see
> > git-switch being prepended to the list rather than entirely replacing
> > git-checkout. For instance:
> >
> >     $ git switch -c foo     <1>
> >     $ git checkout -b foo   <1>
> >     $ git branch foo        <2>
> >     $ git tag foo           <3>
>
> That can invite "do we need to use checkout after doing switch?"
> confusion.  I would understand if it were
>
>         $ git checkout -b foo # or "git switch -c foo" <1>
>
> or something that makes it clear either one, but not both, is used
> there.

That refinement looks good to me.

Re: [PATCH] doc: use "git switch -c" rather than "git checkout -b" consistently

[Yutaro Ohno]

Eric Sunshine <sunshine@sunshineco.com> wrote:
> On Mon, Jan 9, 2023 at 1:30 AM Junio C Hamano <gitster@pobox.com> wrote:
> > Eric Sunshine <sunshine@sunshineco.com> writes:
> > > touches is given merely as examples one might use, then I could see
> > > git-switch being prepended to the list rather than entirely replacing
> > > git-checkout. For instance:
> > >
> > >     $ git switch -c foo     <1>
> > >     $ git checkout -b foo   <1>
> > >     $ git branch foo        <2>
> > >     $ git tag foo           <3>
> >
> > That can invite "do we need to use checkout after doing switch?"
> > confusion.  I would understand if it were
> >
> >         $ git checkout -b foo # or "git switch -c foo" <1>
> >
> > or something that makes it clear either one, but not both, is used
> > there.

This looks good. I'll send a v2 patch. Thank you!

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

[Yutaro Ohno via GitGitGadget]

From: Yutaro Ohno <yutaro.ono.418@gmail.com>

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 <yutaro.ono.418@gmail.com>
---
    doc: add "git switch -c" as another option on detached HEAD
    
    cc: Eric Sunshine sunshine@sunshineco.com

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 <yutaro.ono.418@gmail.com>
      
       ## 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 <yutaro.ono.418@gmail.com>
      
     @@ 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

RE: [PATCH] doc: use "git switch -c" rather than "git checkout -b" consistently

[rsbecker]

On January 8, 2023 11:31 PM, Junio C Hamano wrote:
>"Yutaro Ohno via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
>> From: Yutaro Ohno <yutaro.ono.418@gmail.com>
>> Subject: Re: [PATCH] doc: use "git switch -c" rather than "git
>> checkout -b" consistently
>
>Hmph.  When two things work equally well, is it a good idea to describe
only one
>"consistently", or mention both that can be used pretty much
interchangeably in
>different places?  I am not 100% sure "consistently" is a good thing here.
>
>Thoughts from others?

git switch is still marked as EXPERIMENTAL in the online help. I don't think
moving broadly to switch from checkout in the documentation should happen
until the EXPERIMENTAL designation is dropped. After that, then "switch -c"
should be used everywhere instead of checkout (except for in the checkout
documentation).

--Randall

Re: [PATCH] doc: use "git switch -c" rather than "git checkout -b" consistently

[Eric Sunshine]

On Mon, Jan 9, 2023 at 6:20 AM <rsbecker@nexbridge.com> wrote:
> On January 8, 2023 11:31 PM, Junio C Hamano wrote:
> >"Yutaro Ohno via GitGitGadget" <gitgitgadget@gmail.com> writes:
> >> Subject: Re: [PATCH] doc: use "git switch -c" rather than "git
> >> checkout -b" consistently
> >
> >Hmph.  When two things work equally well, is it a good idea to describe
> only one
> >"consistently", or mention both that can be used pretty much
> interchangeably in
> >different places?  I am not 100% sure "consistently" is a good thing here.
> >
> >Thoughts from others?
>
> git switch is still marked as EXPERIMENTAL in the online help. I don't think
> moving broadly to switch from checkout in the documentation should happen
> until the EXPERIMENTAL designation is dropped. After that, then "switch -c"
> should be used everywhere instead of checkout (except for in the checkout
> documentation).

Such a point probably should have been raised when 328c6cb853 (doc:
promote "git switch", 2019-03-29) was submitted, but since 328c6cb853
was merged nearly four years ago and has been pointing people at
git-switch all this time, it's probably too late to use it as an
argument now.

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

[Eric Sunshine]

On Mon, Jan 9, 2023 at 5:53 AM Yutaro Ohno via GitGitGadget
<gitgitgadget@gmail.com> 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 <yutaro.ono.418@gmail.com>
> ---
> 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/CAPig+cQe_VMW2KV+ZyZwosFw07Q+hePryDVushRJ-jFfD4yzpw@mail.gmail.com/
[2]: https://lore.kernel.org/git/xmqqk01wusmz.fsf@gitster.g/
[3]: https://lore.kernel.org/git/CAPig+cTO1jBjcwjX4UpxG813OwrDAaYVvViC_XGWorwbXvOfvw@mail.gmail.com/

RE: [PATCH] doc: use "git switch -c" rather than "git checkout -b" consistently

[rsbecker]

On January 9, 2023 2:17 PM, Eric Sunshine wrote:
>On Mon, Jan 9, 2023 at 6:20 AM <rsbecker@nexbridge.com> wrote:
>> On January 8, 2023 11:31 PM, Junio C Hamano wrote:
>> >"Yutaro Ohno via GitGitGadget" <gitgitgadget@gmail.com> writes:
>> >> Subject: Re: [PATCH] doc: use "git switch -c" rather than "git
>> >> checkout -b" consistently
>> >
>> >Hmph.  When two things work equally well, is it a good idea to
>> >describe
>> only one
>> >"consistently", or mention both that can be used pretty much
>> interchangeably in
>> >different places?  I am not 100% sure "consistently" is a good thing here.
>> >
>> >Thoughts from others?
>>
>> git switch is still marked as EXPERIMENTAL in the online help. I don't
>> think moving broadly to switch from checkout in the documentation
>> should happen until the EXPERIMENTAL designation is dropped. After that, then
>"switch -c"
>> should be used everywhere instead of checkout (except for in the
>> checkout documentation).
>
>Such a point probably should have been raised when 328c6cb853 (doc:
>promote "git switch", 2019-03-29) was submitted, but since 328c6cb853 was
>merged nearly four years ago and has been pointing people at git-switch all this
>time, it's probably too late to use it as an argument now.

I agree. Perhaps it is time to drop the "EXPERIMENTAL" notices from 'git switch', in that case.

Re: [PATCH] doc: use "git switch -c" rather than "git checkout -b" consistently

[Eric Sunshine]

On Mon, Jan 9, 2023 at 2:58 PM <rsbecker@nexbridge.com> wrote:
> On January 9, 2023 2:17 PM, Eric Sunshine wrote:
> >On Mon, Jan 9, 2023 at 6:20 AM <rsbecker@nexbridge.com> wrote:
> >> git switch is still marked as EXPERIMENTAL in the online help. I don't
> >> think moving broadly to switch from checkout in the documentation
> >> should happen until the EXPERIMENTAL designation is dropped. After that, then
> >"switch -c"
> >> should be used everywhere instead of checkout (except for in the
> >> checkout documentation).
> >
> >Such a point probably should have been raised when 328c6cb853 (doc:
> >promote "git switch", 2019-03-29) was submitted, but since 328c6cb853 was
> >merged nearly four years ago and has been pointing people at git-switch all this
> >time, it's probably too late to use it as an argument now.
>
> I agree. Perhaps it is time to drop the "EXPERIMENTAL" notices from 'git switch', in that case.

Perhaps. Perhaps not. As I recall, both Felipe and Ævar expressed
rather serious concerns that git-switch is not yet ready as a proper
git-checkout replacement. Samples of their concerns can be found at
[1] and [2], for instance.

By the way, git-worktree is even older and probably more widely used
than git-switch, yet it is still marked "experimental", as well, and
perhaps rightly so. As far as I understand, for instance, it still
isn't compatible with submodules (though there may have been some
recent work from one of the Googlers in that area?).

[1]: https://lore.kernel.org/git/211021.86wnm6l1ip.gmgdl@evledraar.gmail.com/
[2]: https://lore.kernel.org/git/CAPiPmQnb=XMaF2+YkryEbiX8zA=jwa5y=fbAGk9jpCExpbS4Rw@mail.gmail.com/T/

Re: [PATCH] doc: use "git switch -c" rather than "git checkout -b" consistently

[Ævar Arnfjörð Bjarmason]

On Mon, Jan 09 2023, Eric Sunshine wrote:

> On Mon, Jan 9, 2023 at 2:58 PM <rsbecker@nexbridge.com> wrote:
>> On January 9, 2023 2:17 PM, Eric Sunshine wrote:
>> >On Mon, Jan 9, 2023 at 6:20 AM <rsbecker@nexbridge.com> wrote:
>> >> git switch is still marked as EXPERIMENTAL in the online help. I don't
>> >> think moving broadly to switch from checkout in the documentation
>> >> should happen until the EXPERIMENTAL designation is dropped. After that, then
>> >"switch -c"
>> >> should be used everywhere instead of checkout (except for in the
>> >> checkout documentation).
>> >
>> >Such a point probably should have been raised when 328c6cb853 (doc:
>> >promote "git switch", 2019-03-29) was submitted, but since 328c6cb853 was
>> >merged nearly four years ago and has been pointing people at git-switch all this
>> >time, it's probably too late to use it as an argument now.
>>
>> I agree. Perhaps it is time to drop the "EXPERIMENTAL" notices from 'git switch', in that case.
>
> Perhaps. Perhaps not. As I recall, both Felipe and Ævar expressed
> rather serious concerns that git-switch is not yet ready as a proper
> git-checkout replacement. Samples of their concerns can be found at
> [1] and [2], for instance.
>
> By the way, git-worktree is even older and probably more widely used
> than git-switch, yet it is still marked "experimental", as well, and
> perhaps rightly so. As far as I understand, for instance, it still
> isn't compatible with submodules (though there may have been some
> recent work from one of the Googlers in that area?).
>
> [1]: https://lore.kernel.org/git/211021.86wnm6l1ip.gmgdl@evledraar.gmail.com/
> [2]: https://lore.kernel.org/git/CAPiPmQnb=XMaF2+YkryEbiX8zA=jwa5y=fbAGk9jpCExpbS4Rw@mail.gmail.com/T/

I think deciding on the "EXPERIMENTAL" would be nice, and it should
arguably precede wider use of "git switch" in the docs.

But on the other hand we already provide examples of it outside its own
docs, so perhaps a change such as the one being proposed here is
something we should just accept.

Discussions such as these might also suggest that thinking we can change
its fundamental behavior at this point are wishful thinking, i.e. maybe
too many users rely on it, and didn't read the disclaimer.

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

[Junio C Hamano]

Eric Sunshine <sunshine@sunshineco.com> 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'.