| Message ID | pull.1484.git.git.1680257503697.gitgitgadget@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | doc: add that '-' is the same as '@{-1}' | expand |
On Fri, Mar 31, 2023 at 10:11:43AM +0000, ryicoh via GitGitGadget wrote: >+ before the current one. You may also specify - which is synonymous >+ to @{-1}. > i'd recommend quoting the dash as you do in the summary (or adding some markup?), as otherwise it's way too easy to misread.
"ryicoh via GitGitGadget" <gitgitgadget@gmail.com> writes: > diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt > index 9aa58052bc7..9e7ea2cf71e 100644 > --- a/Documentation/revisions.txt > +++ b/Documentation/revisions.txt > @@ -94,7 +94,8 @@ some output processing may assume ref names in UTF-8. > > '@{-<n>}', e.g. '@{-1}':: > The construct '@{-<n>}' means the <n>th branch/commit checked out > - before the current one. > + before the current one. You may also specify - which is synonymous > + to @{-1}. I know the author of the change meant well, but this change makes the resulting text overly broad and misleading by saying `-` is "synonymous". It is certainly *not* synonymous in general and I doubt we want to make it to. $ git switch --detach master $ git reset --hard maint $ git commit --amend -C - fatal: could not look up commit - $ git show - fatal: unrecognized argument: - $ git log ..- fatal: ambiguous argument '..-': unknown revision or path not in the working tree Use '--' to separate paths from revisions, like this: 'git <command> [<revision>...] -- [<file...]' $ git log HEAD..- -- fatal: bad revision 'HEAD..-' There are only few selected places that treat "-" like "@{-1}". The primary motivation behind "-" is to allow those who are so used to see that "cd $there && do something there && cd -" to come back to the original place to do $ git switch there $ hack hack hack $ git switch - ;# or "git checkout -" and the intention is to use it where we do not allow arbitrary commit object name but it is clear we are taking a branch name. "git switch --help" and "git checkout --help" already mention them; if there is another command that uses "-" as "@{-1}" (and not as "the standard input" or "the standard output"), for now we should update its documentation to mention "- can also be used in place of @{-1}". Thanks.
Hi ryicoh On 31/03/2023 11:11, ryicoh via GitGitGadget wrote: > From: ryicoh <ryicoh@gmail.com> > > Signed-off-by: ryicoh <ryicoh@gmail.com> > --- > doc: add that '-' is the same as '@{-1}' A few commands (checkout, merge, rebase and switch spring to mind) accept '-' as a shorthand for '@{-1}' but I don't think it is universally accepted. Best Wishes Phillip > > Now, the document of '-' is written only git-switch.txt. > > https://github.com/git/git/blob/6369acd968d02899973a9a853c48029b92cea401/Documentation/git-switch.txt#L51 > > I want same one in revisions.txt. > > Thank you. > > Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1484%2Fryicoh%2Fdoc-hyphen-v1 > Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1484/ryicoh/doc-hyphen-v1 > Pull-Request: https://github.com/git/git/pull/1484 > > Documentation/revisions.txt | 3 ++- > 1 file changed, 2 insertions(+), 1 deletion(-) > > diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt > index 9aa58052bc7..9e7ea2cf71e 100644 > --- a/Documentation/revisions.txt > +++ b/Documentation/revisions.txt > @@ -94,7 +94,8 @@ some output processing may assume ref names in UTF-8. > > '@{-<n>}', e.g. '@{-1}':: > The construct '@{-<n>}' means the <n>th branch/commit checked out > - before the current one. > + before the current one. You may also specify - which is synonymous > + to @{-1}. > > '[<branchname>]@\{upstream\}', e.g. 'master@\{upstream\}', '@\{u\}':: > A branch B may be set up to build on top of a branch X (configured with > > base-commit: 6369acd968d02899973a9a853c48029b92cea401
Hi Oswald, Junio and Phillip. Thank you for your reviews. Let me reply to each comments. > i'd recommend quoting the dash as you do in the summary (or adding some markup?), as otherwise it's way too easy to misread. That's good. I'll fix it. > It is certainly *not* synonymous in general and I > doubt we want to make it to. That's correct. Your examples helped me understand. > A few commands (checkout, merge, rebase and switch spring to mind) accept '-' as a shorthand for '@{-1}' but I don't think it is universally accepted. That's correct too. > 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}`. Other commands also seem to accept '-', such as `cherry-pick`. It's not good idea to write all commands that accepted it. Best Wishes
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?
diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index 9aa58052bc7..9e7ea2cf71e 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -94,7 +94,8 @@ some output processing may assume ref names in UTF-8. '@{-<n>}', e.g. '@{-1}':: The construct '@{-<n>}' means the <n>th branch/commit checked out - before the current one. + before the current one. You may also specify - which is synonymous + to @{-1}. '[<branchname>]@\{upstream\}', e.g. 'master@\{upstream\}', '@\{u\}':: A branch B may be set up to build on top of a branch X (configured with