From: Junio C Hamano <gitster@pobox•com>
To: ryicoh <ryicoh@gmail•com>
Cc: git@vger•kernel.org, gitgitgadget@gmail•com
Subject: Re: [PATCH] doc: add that '-' is the same as '@{-1}'
Date: Sun, 02 Apr 2023 05:26:24 -0700 [thread overview]
Message-ID: <xmqqsfdia2rz.fsf@gitster.g> (raw)
In-Reply-To: 20230401155342.21230-1-ryicoh@gmail.com
ryicoh <ryicoh@gmail•com> writes:
>> for now we should
>> update its documentation to mention "- can also be used in place of
>> @{-1}".
>
> Finally, How should I update the documentation? How about following changes?
>
> - You may also specify `-` which is synonymous to `@{-1}`.
> + Only some commands (checkout, switch, etc,), you may also specify `-` which is synonymous to `@{-1}`.
I would not do the above, if I were following the "_for now_ we
should". I'd instead go to Documentation/git-foo.txt and imitate
how git-checkout.txt next door describes @{-<N>} and mentions its
special casing of '-'.
When a user is learning the subcommand 'foo' with a feature that is
commonly used in the context of 'foo' and takes a branch (e.g.
"checkout" takes "which branch to check out"), they want to find how
the branch is spelled (e.g. "you can give a branch name, @{-<N>}, ah
by the way "-" is @{-1}") in the documentation for 'foo' where the
feature related to a branch is described. It would make the feature
a lot harder to discover to bury a list of names of only a handful
subcommands that share the same feature, while saying the feature
would not generally be available, in another section whose primary
purpose is to explain how to name an arbitrary revision, not a name
of a branch, no?
next prev parent reply other threads:[~2023-04-02 12:26 UTC|newest]
Thread overview: 6+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-03-31 10:11 [PATCH] doc: add that '-' is the same as '@{-1}' ryicoh via GitGitGadget
2023-03-31 12:03 ` Oswald Buddenhagen
2023-03-31 16:12 ` Junio C Hamano
2023-04-01 15:53 ` ryicoh
2023-04-02 12:26 ` Junio C Hamano [this message]
2023-03-31 16:29 ` Phillip Wood
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=xmqqsfdia2rz.fsf@gitster.g \
--to=gitster@pobox$(echo .)com \
--cc=git@vger$(echo .)kernel.org \
--cc=gitgitgadget@gmail$(echo .)com \
--cc=ryicoh@gmail$(echo .)com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox