{"thread":{"id":"59507","subject":"[PATCH] doc: add that '-' is the same as '@{-1}'","startedAt":"2023-03-31T10:16:40Z","lastAt":"2023-04-02T12:26:29Z","messageCount":6,"participants":["ryicoh via GitGitGadget","Oswald Buddenhagen","Junio C Hamano","Phillip Wood","ryicoh"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"474499","messageId":"pull.1484.git.git.1680257503697.gitgitgadget@gmail.com","threadId":"59507","inReplyTo":null,"subject":"[PATCH] doc: add that '-' is the same as '@{-1}'","fromName":"ryicoh via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-03-31T10:11:43Z","receivedAt":"2023-03-31T10:16:40Z","isPatch":true,"sender":{"key":"ryicoh@gmail.com","avatar":null},"body":"From: ryicoh <ryicoh@gmail.com>\n\nSigned-off-by: ryicoh <ryicoh@gmail.com>\n---\n    doc: add that '-' is the same as '@{-1}'\n    \n    Now, the document of '-' is written only git-switch.txt.\n    \n    https://github.com/git/git/blob/6369acd968d02899973a9a853c48029b92cea401/Documentation/git-switch.txt#L51\n    \n    I want same one in revisions.txt.\n    \n    Thank you.\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1484%2Fryicoh%2Fdoc-hyphen-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1484/ryicoh/doc-hyphen-v1\nPull-Request: https://github.com/git/git/pull/1484\n\n Documentation/revisions.txt | 3 ++-\n 1 file changed, 2 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\nindex 9aa58052bc7..9e7ea2cf71e 100644\n--- a/Documentation/revisions.txt\n+++ b/Documentation/revisions.txt\n@@ -94,7 +94,8 @@ some output processing may assume ref names in UTF-8.\n \n '@{-<n>}', e.g. '@{-1}'::\n   The construct '@{-<n>}' means the <n>th branch/commit checked out\n-  before the current one.\n+  before the current one. You may also specify - which is synonymous\n+  to @{-1}.\n \n '[<branchname>]@\\{upstream\\}', e.g. 'master@\\{upstream\\}', '@\\{u\\}'::\n   A branch B may be set up to build on top of a branch X (configured with\n\nbase-commit: 6369acd968d02899973a9a853c48029b92cea401\n-- \ngitgitgadget\n"},{"id":"474502","messageId":"ZCbMAWsaseAmwmqc@ugly","threadId":"59507","inReplyTo":"pull.1484.git.git.1680257503697.gitgitgadget@gmail.com","subject":"Re: [PATCH] doc: add that '-' is the same as '@{-1}'","fromName":"Oswald Buddenhagen","fromEmail":"oswald.buddenhagen@gmx.de","sentAt":"2023-03-31T12:03:13Z","receivedAt":"2023-03-31T12:03:19Z","isPatch":true,"sender":{"key":"oswald.buddenhagen@gmx.de","avatar":"https://avatars.githubusercontent.com/u/812380?v=4"},"body":"On Fri, Mar 31, 2023 at 10:11:43AM +0000, ryicoh via GitGitGadget wrote:\n>+  before the current one. You may also specify - which is synonymous\n>+  to @{-1}.\n> \ni'd recommend quoting the dash as you do in the summary (or adding some \nmarkup?), as otherwise it's way too easy to misread.\n\n"},{"id":"474511","messageId":"xmqqlejchpct.fsf@gitster.g","threadId":"59507","inReplyTo":"pull.1484.git.git.1680257503697.gitgitgadget@gmail.com","subject":"Re: [PATCH] doc: add that '-' is the same as '@{-1}'","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-03-31T16:12:18Z","receivedAt":"2023-03-31T16:18:17Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"ryicoh via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\n> index 9aa58052bc7..9e7ea2cf71e 100644\n> --- a/Documentation/revisions.txt\n> +++ b/Documentation/revisions.txt\n> @@ -94,7 +94,8 @@ some output processing may assume ref names in UTF-8.\n>  \n>  '@{-<n>}', e.g. '@{-1}'::\n>    The construct '@{-<n>}' means the <n>th branch/commit checked out\n> -  before the current one.\n> +  before the current one. You may also specify - which is synonymous\n> +  to @{-1}.\n\nI know the author of the change meant well, but this change makes\nthe resulting text overly broad and misleading by saying `-` is\n\"synonymous\".  It is certainly *not* synonymous in general and I\ndoubt we want to make it to.\n\n  $ git switch --detach master\n  $ git reset --hard maint\n  $ git commit --amend -C -\n  fatal: could not look up commit -\n  $ git show -\n  fatal: unrecognized argument: -\n  $ git log ..-\n  fatal: ambiguous argument '..-': unknown revision or path not in the working tree\n  Use '--' to separate paths from revisions, like this:\n  'git <command> [<revision>...] -- [<file...]'\n  $ git log HEAD..- --\n  fatal: bad revision 'HEAD..-'\n\nThere are only few selected places that treat \"-\" like \"@{-1}\".  The\nprimary motivation behind \"-\" is to allow those who are so used to\nsee that \"cd $there && do something there && cd -\" to come back to\nthe original place to do\n\n  $ git switch there\n  $ hack hack hack\n  $ git switch -      ;# or \"git checkout -\"\n\nand the intention is to use it where we do not allow arbitrary\ncommit object name but it is clear we are taking a branch name.\n\n\"git switch --help\" and \"git checkout --help\" already mention them;\nif there is another command that uses \"-\" as \"@{-1}\" (and not as\n\"the standard input\" or \"the standard output\"), for now we should\nupdate its documentation to mention \"- can also be used in place of\n@{-1}\".\n\nThanks.\n"},{"id":"474513","messageId":"6c2c663d-9d91-3395-5dd5-844d6daef57a@dunelm.org.uk","threadId":"59507","inReplyTo":"pull.1484.git.git.1680257503697.gitgitgadget@gmail.com","subject":"Re: [PATCH] doc: add that '-' is the same as '@{-1}'","fromName":"Phillip Wood","fromEmail":"phillip.wood123@gmail.com","sentAt":"2023-03-31T16:29:48Z","receivedAt":"2023-03-31T16:33:43Z","isPatch":true,"sender":{"key":"phillip.wood@dunelm.org.uk","avatar":null},"body":"Hi ryicoh\n\nOn 31/03/2023 11:11, ryicoh via GitGitGadget wrote:\n> From: ryicoh <ryicoh@gmail.com>\n> \n> Signed-off-by: ryicoh <ryicoh@gmail.com>\n> ---\n>      doc: add that '-' is the same as '@{-1}'\n\nA few commands (checkout, merge, rebase and switch spring to mind) \naccept '-' as a shorthand for '@{-1}' but I don't think it is \nuniversally accepted.\n\nBest Wishes\n\nPhillip\n\n>      \n>      Now, the document of '-' is written only git-switch.txt.\n>      \n>      https://github.com/git/git/blob/6369acd968d02899973a9a853c48029b92cea401/Documentation/git-switch.txt#L51\n>      \n>      I want same one in revisions.txt.\n>      \n>      Thank you.\n> \n> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1484%2Fryicoh%2Fdoc-hyphen-v1\n> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1484/ryicoh/doc-hyphen-v1\n> Pull-Request: https://github.com/git/git/pull/1484\n> \n>   Documentation/revisions.txt | 3 ++-\n>   1 file changed, 2 insertions(+), 1 deletion(-)\n> \n> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\n> index 9aa58052bc7..9e7ea2cf71e 100644\n> --- a/Documentation/revisions.txt\n> +++ b/Documentation/revisions.txt\n> @@ -94,7 +94,8 @@ some output processing may assume ref names in UTF-8.\n>   \n>   '@{-<n>}', e.g. '@{-1}'::\n>     The construct '@{-<n>}' means the <n>th branch/commit checked out\n> -  before the current one.\n> +  before the current one. You may also specify - which is synonymous\n> +  to @{-1}.\n>   \n>   '[<branchname>]@\\{upstream\\}', e.g. 'master@\\{upstream\\}', '@\\{u\\}'::\n>     A branch B may be set up to build on top of a branch X (configured with\n> \n> base-commit: 6369acd968d02899973a9a853c48029b92cea401\n"},{"id":"474630","messageId":"20230401155342.21230-1-ryicoh@gmail.com","threadId":"59507","inReplyTo":"xmqqlejchpct.fsf@gitster.g","subject":"Re: [PATCH] doc: add that '-' is the same as '@{-1}'","fromName":"ryicoh","fromEmail":"ryicoh@gmail.com","sentAt":"2023-04-01T15:53:42Z","receivedAt":"2023-04-01T15:53:50Z","isPatch":true,"sender":{"key":"ryicoh@gmail.com","avatar":null},"body":"Hi Oswald, Junio and Phillip.\n\nThank you for your reviews. Let me reply to each comments.\n\n> 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.\n\nThat's good. I'll fix it.\n\n> It is certainly *not* synonymous in general and I\n> doubt we want to make it to.\n\nThat's correct. Your examples helped me understand.\n\n> 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.\n\nThat's correct too.\n\n\n> for now we should\n> update its documentation to mention \"- can also be used in place of\n> @{-1}\".\n\nFinally, How should I update the documentation? How about following changes?\n\n- You may also specify `-` which is synonymous to `@{-1}`.\n+ Only some commands (checkout, switch, etc,), you may also specify `-` which is synonymous to `@{-1}`.\n\nOther commands also seem to accept '-', such as `cherry-pick`.\nIt's not good idea to write all commands that accepted it.\n\nBest Wishes\n\n"},{"id":"474658","messageId":"xmqqsfdia2rz.fsf@gitster.g","threadId":"59507","inReplyTo":"20230401155342.21230-1-ryicoh@gmail.com","subject":"Re: [PATCH] doc: add that '-' is the same as '@{-1}'","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-04-02T12:26:24Z","receivedAt":"2023-04-02T12:26:29Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"ryicoh <ryicoh@gmail.com> writes:\n\n>> for now we should\n>> update its documentation to mention \"- can also be used in place of\n>> @{-1}\".\n>\n> Finally, How should I update the documentation? How about following changes?\n>\n> - You may also specify `-` which is synonymous to `@{-1}`.\n> + Only some commands (checkout, switch, etc,), you may also specify `-` which is synonymous to `@{-1}`.\n\nI would not do the above, if I were following the \"_for now_ we\nshould\".  I'd instead go to Documentation/git-foo.txt and imitate\nhow git-checkout.txt next door describes @{-<N>} and mentions its\nspecial casing of '-'.\n\nWhen a user is learning the subcommand 'foo' with a feature that is\ncommonly used in the context of 'foo' and takes a branch (e.g.\n\"checkout\" takes \"which branch to check out\"), they want to find how\nthe branch is spelled (e.g. \"you can give a branch name, @{-<N>}, ah\nby the way \"-\" is @{-1}\") in the documentation for 'foo' where the\nfeature related to a branch is described.  It would make the feature\na lot harder to discover to bury a list of names of only a handful\nsubcommands that share the same feature, while saying the feature\nwould not generally be available, in another section whose primary\npurpose is to explain how to name an arbitrary revision, not a name\nof a branch, no?\n"}]}