doc: add "git switch -c" as another option on detached HEAD #1422
Conversation
Welcome to GitGitGadgetHi @ohno418, and welcome to GitGitGadget, the GitHub App to send patch series to the Git mailing list from GitHub Pull Requests. Please make sure that your Pull Request has a good description, as it will be used as cover letter. You can CC potential reviewers by adding a footer to the PR description with the following syntax: Also, it is a good idea to review the commit messages one last time, as the Git project expects them in a quite specific form:
It is in general a good idea to await the automated test ("Checks") in this Pull Request before contributing the patches, e.g. to avoid trivial issues such as unportable code. Contributing the patchesBefore you can contribute the patches, your GitHub username needs to be added to the list of permitted users. Any already-permitted user can do that, by adding a comment to your PR of the form Both the person who commented An alternative is the channel Once on the list of permitted usernames, you can contribute the patches to the Git mailing list by adding a PR comment If you want to see what email(s) would be sent for a After you submit, GitGitGadget will respond with another comment that contains the link to the cover letter mail in the Git mailing list archive. Please make sure to monitor the discussion in that thread and to address comments and suggestions (while the comments and suggestions will be mirrored into the PR by GitGitGadget, you will still want to reply via mail). If you do not want to subscribe to the Git mailing list just to be able to respond to a mail, you can download the mbox from the Git mailing list archive (click the curl -g --user "<EMailAddress>:<Password>" \
--url "imaps://imap.gmail.com/INBOX" -T /path/to/raw.txtTo iterate on your change, i.e. send a revised patch or patch series, you will first want to (force-)push to the same branch. You probably also want to modify your Pull Request description (or title). It is a good idea to summarize the revision by adding something like this to the cover letter (read: by editing the first comment on the PR, i.e. the PR description): To send a new iteration, just add another PR comment with the contents: Need help?New contributors who want advice are encouraged to join git-mentoring@googlegroups.com, where volunteers who regularly contribute to Git are willing to answer newbie questions, give advice, or otherwise provide mentoring to interested contributors. You must join in order to post or view messages, but anyone can join. You may also be able to find help in real time in the developer IRC channel, |
|
/allow |
|
User ohno418 is now allowed to use GitGitGadget. |
|
/preview |
|
Preview email sent as pull.1422.git.git.1673165289329.gitgitgadget@gmail.com |
|
/submit |
|
Submitted as pull.1422.git.git.1673166241185.gitgitgadget@gmail.com To fetch this version into To fetch this version to local tag |
|
On the Git mailing list, Junio C Hamano wrote (reply to this): "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? |
|
On the Git mailing list, Eric Sunshine wrote (reply to this): 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>
------------ |
|
User |
|
On the Git mailing list, Junio C Hamano wrote (reply to this): 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.
|
|
On the Git mailing list, Eric Sunshine wrote (reply to this): 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. |
|
On the Git mailing list, Yutaro Ohno wrote (reply to this): 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! |
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>
ohno418
force-pushed
the
improve-git-checkout-doc
branch
from
b7a1145
to
2103912
Compare
ohno418
changed the title
|
/submit |
|
Submitted as pull.1422.v2.git.git.1673261237449.gitgitgadget@gmail.com To fetch this version into To fetch this version to local tag |
|
On the Git mailing list, wrote (reply to this): 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
|
|
User |
|
On the Git mailing list, Eric Sunshine wrote (reply to this): 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. |
|
On the Git mailing list, Eric Sunshine wrote (reply to this): 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/ |
|
On the Git mailing list, wrote (reply to this): 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.
|
|
On the Git mailing list, Eric Sunshine wrote (reply to this): 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/ |
|
On the Git mailing list, Ævar Arnfjörð Bjarmason wrote (reply to this): 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. |
|
User |
|
On the Git mailing list, Junio C Hamano wrote (reply to this): 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'. |
|
This branch is now known as |
|
This patch series was integrated into seen via de719e5. |
|
This patch series was integrated into seen via b6547c4. |
|
This patch series was integrated into seen via 53071ff. |
|
This patch series was integrated into seen via b6fc67e. |
|
There was a status update in the "New Topics" section about the branch Doc update. Will merge to 'next'. source: <pull.1422.v2.git.git.1673261237449.gitgitgadget@gmail.com> |
|
This patch series was integrated into seen via 5c66c10. |
|
This patch series was integrated into seen via ef5fc6f. |
|
This patch series was integrated into seen via 72716e8. |
|
This patch series was integrated into seen via 6e994e9. |
|
This patch series was integrated into next via 7169d5d. |
|
This patch series was integrated into seen via d84bf0c. |
|
This patch series was integrated into seen via 912c096. |
|
This patch series was integrated into seen via 8c19ca1. |
|
There was a status update in the "Cooking" section about the branch Doc update. Will merge to 'master'. source: <pull.1422.v2.git.git.1673261237449.gitgitgadget@gmail.com> |
|
This patch series was integrated into seen via 472eed5. |
|
There was a status update in the "Graduated to 'master'" section about the branch Doc update. source: <pull.1422.v2.git.git.1673261237449.gitgitgadget@gmail.com> |
|
This patch series was integrated into seen via b106341. |
|
This patch series was integrated into master via b106341. |
|
This patch series was integrated into next via b106341. |
|
Closed via b106341. |
cc: Eric Sunshine sunshine@sunshineco.com
cc: rsbecker@nexbridge.com
cc: Ævar Arnfjörð Bjarmason avarab@gmail.com