doc: add that '-' is the same as '@{-1}'
PATCH 1/1 doc: add that '-' is the same as '@{-1}'
From: ryicoh <[email protected]>
---
doc: add that '-' is the same as '@{-1}'
Now, the document of '-' is written only git-switch.txt.
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(-)
Documentation/revisions.txt +2 -1
@@ -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
Signature · 1 line
gitgitgadget
Documentation/revisions.txt some output processing may assume ref names in UTF-8. · line 98
Quoted 3 lines · ryicoh via GitGitGadget
Documentation/revisions.txt +2
-0+ 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.
Documentation/revisions.txt some output processing may assume ref names in UTF-8. · line 98
Quoted 11 lines · ryicoh via GitGitGadget
Documentation/revisions.txt +2
-1@@ -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 Oswald, Junio and Phillip.
Thank you for your reviews. Let me reply to each comments.
Quoted 1 line
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.
Quoted 2 lines
It is certainly *not* synonymous in general and I
doubt we want to make it to.
That's correct. Your examples helped me understand.
Quoted 1 line
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.
Quoted 3 lines
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
Quoted 8 lines · ryicoh
Quoted 3 lines
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?
Hi ryicoh
Quoted 5 lines · ryicoh via GitGitGadget
From: ryicoh <[email protected]>
Signed-off-by ryicoh <[email protected]>---
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
Quoted 32 lines
Now, the document of '-' is written only git-switch.txt.
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/1484Documentation/revisions.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)Documentation/revisions.txt +2
-1@@ -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 withbase-commit:
6369acd968d02899973a9a853c48029b92cea401