Skip to contentSkip to conversation

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

PATCH In review Yutaro Ohno via GitGitGadget 6 participants 14 messages Jan 8, 2023 – Jan 13, 2023 Documentation

lore
Share & tools
lore

Yutaro Ohno via GitGitGadget

author
#0 lore raw

PATCH 1/1 doc: use "git switch -c" rather than "git checkout -b" consistently

From: Yutaro Ohno <[email protected]>

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 <[email protected]>

---
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(-)
Documentation/git-checkout.txt +3 -3
index 4cb9d555b4b..ba3d6164847 100644
@@ -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

Signature · 1 line
gitgitgadget
#1 lore raw
Quoted 2 lines · Yutaro Ohno via GitGitGadget

From: Yutaro Ohno <[email protected]>
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?

#2 lore raw
Quoted 9 lines · Junio C Hamano
Quoted 2 lines

From: Yutaro Ohno <[email protected]>
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>
------------

#3 lore raw
Quoted 7 lines · Eric Sunshine

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:

Quoted 6 lines

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

#4 lore raw
Quoted 10 lines · Junio C Hamano
Quoted 8 lines · Eric Sunshine

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>
Quoted 7 lines

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.

#5 lore raw
Quoted 11 lines · Eric Sunshine
Quoted 10 lines · Junio C Hamano
Quoted 8 lines · Eric Sunshine

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>
Quoted 7 lines
Quoted 7 lines

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!

#6 lore raw
In reply to Junio C Hamano
Quoted 7 lines · Junio C Hamano
Quoted 3 lines · Yutaro Ohno via GitGitGadget

From: Yutaro Ohno <[email protected]>
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

Quoted 1 line

"consistently", or mention both that can be used pretty much

interchangeably in

Quoted 3 lines

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

#7 lore raw
Quoted 11 lines · On Mon, Jan 9, 2023 at 6:20 AM <[email protected]> wrote:
Quoted 5 lines · Junio C Hamano
Quoted 2 lines · Yutaro Ohno via GitGitGadget

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

Quoted 1 line

"consistently", or mention both that can be used pretty much

interchangeably in

Quoted 2 lines

different places? I am not 100% sure "consistently" is a good thing here.

Quoted 7 lines
Quoted 1 line

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.

#8 lore raw
Quoted 18 lines · Eric Sunshine
Quoted 9 lines · On Mon, Jan 9, 2023 at 6:20 AM <[email protected]> wrote:
Quoted 6 lines · Junio C Hamano
Quoted 2 lines · Yutaro Ohno via GitGitGadget

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

Quoted 1 line

"consistently", or mention both that can be used pretty much

Quoted 8 lines

interchangeably in

Quoted 3 lines

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

Quoted 8 lines

"switch -c"

Quoted 2 lines

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.

#9 lore raw
Quoted 9 lines · On Mon, Jan 9, 2023 at 2:58 PM <[email protected]> wrote:
Quoted 8 lines · Eric Sunshine
Quoted 3 lines · On Mon, Jan 9, 2023 at 6:20 AM <[email protected]> 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"

Quoted 2 lines

should be used everywhere instead of checkout (except for in the checkout documentation).

Quoted 6 lines
Quoted 4 lines

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/[email protected]/
[2]: https://lore.kernel.org/git/CAPiPmQnb=XMaF2+YkryEbiX8zA=jwa5y=fbAGk9jpCExpbS4Rw@mail.gmail.com/T/

#10 lore raw
Quoted 22 lines · Eric Sunshine
Quoted 9 lines · On Mon, Jan 9, 2023 at 2:58 PM <[email protected]> wrote:
Quoted 8 lines · Eric Sunshine
Quoted 3 lines · On Mon, Jan 9, 2023 at 6:20 AM <[email protected]> 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"

Quoted 2 lines

should be used everywhere instead of checkout (except for in the checkout documentation).

Quoted 6 lines
Quoted 4 lines

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.

Quoted 8 lines

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/[email protected]/
[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.

author
#11 lore raw

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

In reply to Yutaro Ohno via GitGitGadget

From: Yutaro Ohno <[email protected]>

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 protected]>

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

cc Eric Sunshine [email protected]

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 protected]>

## 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 protected]>

@@ 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(-)
Documentation/git-checkout.txt +3 -3
index 4cb9d555b4b..9f116acdbd6 100644
@@ -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

Signature · 1 line
gitgitgadget
#12 lore raw

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

Quoted 14 lines · Yutaro Ohno via GitGitGadget

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 protected]>

---

Documentation/git-checkout.txt before that happens. If we have not yet moved away from commit `f`, · line 481

Quoted 8 lines
Documentation/git-checkout.txt +3 -3
@@ -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/[email protected]/
[3]: https://lore.kernel.org/git/CAPig+cTO1jBjcwjX4UpxG813OwrDAaYVvViC_XGWorwbXvOfvw@mail.gmail.com/

#13 lore raw

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

Quoted 1 line · Eric Sunshine

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

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