threads / patch / 59049

patchdoc: use "git switch -c" rather than "git checkout -b" consistently

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

## tl;dr

14 messages between Jan 8, 2023 and Jan 13, 2023. Diffs are folded; open one to read it.

replies: 13people: 5as markdown or json

Yutaro Ohno via GitGitGadget· Jan 8, 2023, 08:24 UTC · lore
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(-)
Show changes to Documentation/git-checkout.txt +3 −3
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
Junio C Hamano· Jan 9, 2023, 04:30 UTC · re: Yutaro Ohno via GitGitGadget · lore

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

"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?
Eric Sunshine· Jan 9, 2023, 04:48 UTC · re: Junio C Hamano · lore

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

On Sun, Jan 8, 2023 at 11:36 PM Junio C Hamano <gitster@pobox.com> wrote:
Show 9 quoted lines
> > 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>
    ------------
Junio C Hamano· Jan 9, 2023, 06:30 UTC · re: Eric Sunshine · lore

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

Eric Sunshine <sunshine@sunshineco.com> writes:
Show 13 quoted lines
> 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.
Eric Sunshine· Jan 9, 2023, 06:32 UTC · re: Junio C Hamano · lore

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

On Mon, Jan 9, 2023 at 1:30 AM Junio C Hamano <gitster@pobox.com> wrote:
Show 17 quoted lines
> 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.
Yutaro Ohno· Jan 9, 2023, 08:47 UTC · re: Eric Sunshine · lore

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

Eric Sunshine <sunshine@sunshineco.com> wrote:
Show 18 quoted lines
> 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!
rsbecker@nexbridge.com· Jan 9, 2023, 11:17 UTC · re: Junio C Hamano · lore

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

On January 8, 2023 11:31 PM, Junio C Hamano wrote:
Show 7 quoted lines
>"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
Eric Sunshine· Jan 9, 2023, 19:16 UTC · re: rsbecker@nexbridge.com · lore

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

On Mon, Jan 9, 2023 at 6:20 AM <rsbecker@nexbridge.com> wrote:
Show 18 quoted lines
> 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.

rsbecker@nexbridge.com· Jan 9, 2023, 19:58 UTC · re: Eric Sunshine · lore

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

On January 9, 2023 2:17 PM, Eric Sunshine wrote:
Show 26 quoted lines
>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.
Eric Sunshine· Jan 9, 2023, 21:08 UTC · re: rsbecker@nexbridge.com · lore

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

On Mon, Jan 9, 2023 at 2:58 PM <rsbecker@nexbridge.com> wrote:
Show 15 quoted lines
> 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/

Ævar Arnfjörð Bjarmason· Jan 9, 2023, 21:24 UTC · re: Eric Sunshine · lore

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

On Mon, Jan 09 2023, Eric Sunshine wrote:
Show 30 quoted lines
> 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.

Yutaro Ohno via GitGitGadget· Jan 9, 2023, 10:47 UTC · re: Yutaro Ohno via GitGitGadget · lore

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

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(-)
Show changes to Documentation/git-checkout.txt +3 −3
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
Eric Sunshine· Jan 9, 2023, 19:53 UTC · re: Yutaro Ohno via GitGitGadget · lore

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

On Mon, Jan 9, 2023 at 5:53 AM Yutaro Ohno via GitGitGadget <gitgitgadget@gmail.com> wrote:

Show 22 quoted lines
> 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/

Junio C Hamano· Jan 13, 2023, 17:58 UTC · re: Eric Sunshine · lore

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

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

← back to recent threads