{"thread":{"id":"53849","subject":"[PATCH 1/2] git-diff.txt: don't mark required argument as optional","startedAt":"2020-07-13T19:10:46Z","lastAt":"2020-07-15T02:45:52Z","messageCount":7,"participants":["Martin Ågren","Junio C Hamano","Chris Torek"],"isPatch":true,"patchVersion":1,"patchTotal":2},"messages":[{"id":"401498","messageId":"cover.1594666410.git.martin.agren@gmail.com","threadId":"53849","inReplyTo":null,"subject":"[PATCH 0/2] git-diff.txt: reorder possible usages","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2020-07-13T19:10:07Z","receivedAt":"2020-07-13T19:10:46Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"Going through the doc-diff between v2.27.0 and v2.28.0-rc0, I only\nnoticed some small things related to b7e10b2ca2 (\"Documentation: usage\nfor diff combined commits\", 2020-06-12). The first issue might not be\nsomething a lot of people would stumble on, but the second one could\nprobably trip someone up.\n\nAll feedback welcome.\n\nMartin\n\nMartin Ågren (2):\n git-diff.txt: don't mark required argument as optional\n git-diff.txt: reorder possible usages\n\n Documentation/git-diff.txt | 15 ++++++++-------\n 1 file changed, 8 insertions(+), 7 deletions(-)\n\n-- \n2.28.0.rc0\n\n"},{"id":"401496","messageId":"77e4442ae51a968d460b2329fc39b6a5e96902b0.1594666410.git.martin.agren@gmail.com","threadId":"53849","inReplyTo":"cover.1594666410.git.martin.agren@gmail.com","subject":"[PATCH 1/2] git-diff.txt: don't mark required argument as optional","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2020-07-13T19:10:08Z","receivedAt":"2020-07-13T19:10:51Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"Commit b7e10b2ca2 (\"Documentation: usage for diff combined commits\",\n2020-06-12) modified the synopsis by adding an optional \"[...]\"\nto\n\n 'git diff' [] [--] [...]\n\nto effectively add\n\n 'git diff' [] ... [--] [...]\n\nas another valid invocation. Which makes sense.\n\nFurther down, in the description, it left the existing entry for\n\n 'git diff' [] [--] [...]\n\nintact and added a new entry on\n\n 'git diff' [] [...] [--] [...]\n\nwhere it says that \"[t]his form is to view the results of a merge\ncommit\" and details how \"the first listed commit must be the merge\nitself\". But one possible instantiation of this form is `git diff\n ` for which the added text doesn't really apply.\n\nRemove the brackets so that we lose this overlap between the two\ndescriptions. We can still use the more compact representation in the\nsynopsis.\n\nSigned-off-by: Martin Ågren \n---\n Documentation/git-diff.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt\nindex 1018110ddc..c613e71ca4 100644\n--- a/Documentation/git-diff.txt\n+++ b/Documentation/git-diff.txt\n@@ -69,7 +69,7 @@ files on disk.\n \tone side is omitted, it will have the same effect as\n \tusing HEAD instead.\n \n-'git diff' [] [...] [--] [...]::\n+'git diff' [] ... [--] [...]::\n \n \tThis form is to view the results of a merge commit. The first\n \tlisted must be the merge itself; the remaining two or\n-- \n2.28.0.rc0\n\n"},{"id":"401497","messageId":"280943ef56a2a777ab0162b8ec4ba0166cc2095c.1594666410.git.martin.agren@gmail.com","threadId":"53849","inReplyTo":"cover.1594666410.git.martin.agren@gmail.com","subject":"[PATCH 2/2] git-diff.txt: reorder possible usages","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2020-07-13T19:10:09Z","receivedAt":"2020-07-13T19:10:55Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"The description of `git diff` goes through several different invocations\n(numbering added by me):\n\n 1. git diff [] [--] [...]\n 2. git diff [] --no-index [--] \n 3. git diff [] --cached [] [--] [...]\n 4. git diff [] [--] [...]\n 5. git diff [] [--] [...]\n 6. git diff [] .. [--] [...]\n 7. git diff [] ... [--] [...]\n 8. git diff [] ... [--] [...]\n\nIt then goes on to say that \"all of the in the above\ndescription, except in the last two forms that use '..' notations, can\nbe any \". The \"last two\" actually refers to 6 and 8. This got out\nof sync in commit b7e10b2ca2 (\"Documentation: usage for diff combined\ncommits\", 2020-06-12) which added item 7 to the mix.\n\nAs a further complication, after b7e10b2ca2 we also have some potential\nconfusion around \"the '..' notation\". The \"..[.]\" in items 6 and 8 are\npart of the rev notation, whereas the \"...\" in item 7 is manpage\nlanguage for \"one or more\".\n\nMove item 6 down, i.e., to between 7 and 8, to restore the ordering.\nBecause 6 refers to 5 (\"synonymous to the previous form\") we need to\ntweak the language a bit.\n\nAn added bonus of this commit is that we're trying to steer users away\nfrom `git diff ..` and moving it further down probably\ndoesn't hurt.\n\nSigned-off-by: Martin Ågren \n---\n Documentation/git-diff.txt | 13 +++++++------\n 1 file changed, 7 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt\nindex c613e71ca4..727f24d16e 100644\n--- a/Documentation/git-diff.txt\n+++ b/Documentation/git-diff.txt\n@@ -63,12 +63,6 @@ files on disk.\n \tThis is to view the changes between two arbitrary\n \t.\n \n-'git diff' [] .. [--] [...]::\n-\n-\tThis is synonymous to the previous form. If on\n-\tone side is omitted, it will have the same effect as\n-\tusing HEAD instead.\n-\n 'git diff' [] ... [--] [...]::\n \n \tThis form is to view the results of a merge commit. The first\n@@ -78,6 +72,13 @@ files on disk.\n \tFor instance, if `master` names a merge commit, `git diff master\n \tmaster^@` gives the same combined diff as `git show master`.\n \n+'git diff' [] .. [--] [...]::\n+\n+\tThis is synonymous to the earlier form (without the \"..\") for\n+\tviewing the changes between two arbitrary . If on\n+\tone side is omitted, it will have the same effect as\n+\tusing HEAD instead.\n+\n 'git diff' [] \\... [--] [...]::\n \n \tThis form is to view the changes on the branch containing\n-- \n2.28.0.rc0\n\n"},{"id":"401506","messageId":"xmqq365vnqqa.fsf@gitster.c.googlers.com","threadId":"53849","inReplyTo":"77e4442ae51a968d460b2329fc39b6a5e96902b0.1594666410.git.martin.agren@gmail.com","subject":"Re: [PATCH 1/2] git-diff.txt: don't mark required argument as optional","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-07-13T19:45:49Z","receivedAt":"2020-07-13T19:45:55Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Martin Ågren writes:\n\n> Commit b7e10b2ca2 (\"Documentation: usage for diff combined commits\",\n> 2020-06-12) modified the synopsis by adding an optional \"[...]\"\n> to\n>\n> 'git diff' [] [--] [...]\n>\n> to effectively add\n>\n> 'git diff' [] ... [--] [...]\n>\n> as another valid invocation. Which makes sense.\n>\n> Further down, in the description, it left the existing entry for\n>\n> 'git diff' [] [--] [...]\n>\n> intact and added a new entry on\n>\n> 'git diff' [] [...] [--] [...]\n>\n> where it says that \"[t]his form is to view the results of a merge\n> commit\" and details how \"the first listed commit must be the merge\n> itself\". But one possible instantiation of this form is `git diff\n> ` for which the added text doesn't really apply.\n>\n> Remove the brackets so that we lose this overlap between the two\n> descriptions. We can still use the more compact representation in the\n> synopsis.\n>\n> Signed-off-by: Martin Ågren \n> ---\n> Documentation/git-diff.txt | 2 +-\n> 1 file changed, 1 insertion(+), 1 deletion(-)\n>\n> diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt\n> index 1018110ddc..c613e71ca4 100644\n> --- a/Documentation/git-diff.txt\n> +++ b/Documentation/git-diff.txt\n> @@ -69,7 +69,7 @@ files on disk.\n> \tone side is omitted, it will have the same effect as\n> \tusing HEAD instead.\n> \n> -'git diff' [] [...] [--] [...]::\n> +'git diff' [] ... [--] [...]::\n\nThanks.\n\n> \n> \tThis form is to view the results of a merge commit. The first\n> \tlisted must be the merge itself; the remaining two or\n"},{"id":"401520","messageId":"CAPx1Gve7Sy5BUdRztVoVNVZgdqm14dvD=36eYzLPed5YMQeMEQ@mail.gmail.com","threadId":"53849","inReplyTo":"280943ef56a2a777ab0162b8ec4ba0166cc2095c.1594666410.git.martin.agren@gmail.com","subject":"Re: [PATCH 2/2] git-diff.txt: reorder possible usages","fromName":"Chris Torek","fromEmail":"chris.torek@gmail.com","sentAt":"2020-07-13T22:04:23Z","receivedAt":"2020-07-13T22:04:36Z","isPatch":true,"sender":{"key":"chris.torek@gmail.com","avatar":"https://avatars.githubusercontent.com/u/16826774?v=4"},"body":"On Mon, Jul 13, 2020 at 12:10 PM Martin Ågren wrote:\n> It then goes on to say that \"all of the in the above\n> description, except in the last two forms that use '..' notations, can\n> be any \". The \"last two\" actually refers to 6 and 8. This got out\n> of sync in commit b7e10b2ca2 (\"Documentation: usage for diff combined\n> commits\", 2020-06-12) which added item 7 to the mix.\n\nMoving this down (as you do in this patch) is the right thing to do,\nbut I'll note that formally, the word \"that\" in \"forms that use ...\" is\npart of a restrictive clause, so it means \"find the last two examples\nthat use dots\". (In American English at least, the unrestrictive version\nwould be set off with commas, and use \"which\" instead of \"that\".)\n\n> An added bonus of this commit is that we're trying to steer users away\n> from `git diff ..` and moving it further down probably\n> doesn't hurt.\n\nQ: Just how hard should we try? In particular, would it be good to mark\nthe two-dot form as deprecated in the documentation? I anticipate\nobjections because it's not possible to omit `HEAD` without using\nthe two-dot form.\n\nChris\n"},{"id":"401549","messageId":"CAN0heSoNFdLzxV2GV=KDafypLkQmxc28RdKzJtHcVFHx3P97Jg@mail.gmail.com","threadId":"53849","inReplyTo":"CAPx1Gve7Sy5BUdRztVoVNVZgdqm14dvD=36eYzLPed5YMQeMEQ@mail.gmail.com","subject":"Re: [PATCH 2/2] git-diff.txt: reorder possible usages","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2020-07-14T14:49:58Z","receivedAt":"2020-07-14T14:50:18Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On Tue, 14 Jul 2020 at 00:04, Chris Torek wrote:\n>\n> On Mon, Jul 13, 2020 at 12:10 PM Martin Ågren wrote:\n> > It then goes on to say that \"all of the in the above\n> > description, except in the last two forms that use '..' notations, can\n> > be any \". The \"last two\" actually refers to 6 and 8. This got out\n> > of sync in commit b7e10b2ca2 (\"Documentation: usage for diff combined\n> > commits\", 2020-06-12) which added item 7 to the mix.\n>\n> Moving this down (as you do in this patch) is the right thing to do,\n> but I'll note that formally, the word \"that\" in \"forms that use ...\" is\n> part of a restrictive clause, so it means \"find the last two examples\n> that use dots\". (In American English at least, the unrestrictive version\n> would be set off with commas, and use \"which\" instead of \"that\".)\n\nThanks, I hadn't read it like that, that makes sense. I'll learn to pay\nmore attention to the difference between \"that\" and \"which\", which(!)\nI'm not sure I've fully appreciated before. So if one qualifies the \"..\nnotations\" a bit, one might actually achieve something that passes,\nlanguage-lawyer-wise, even in light of the two completely different uses\nof \"..\":\n\n ..., except in the last two forms that use \"..\" range notations, ...\n\nor, if \"the last two forms\" doesn't actually add anything,\n\n ..., except in the forms that use \"..\" range notations, ...\n\nBut I'm not sure that would help users at all, even if we might be able\nto say, \"well, technically, it's all correct..\". ;-) \"The last two\"\nseems more helpful to the reader, although it does carry the risk of\ngetting outdated.\n\nI'm glad you agree with the move.\n\n> > An added bonus of this commit is that we're trying to steer users away\n> > from `git diff ..` and moving it further down probably\n> > doesn't hurt.\n>\n> Q: Just how hard should we try? In particular, would it be good to mark\n> the two-dot form as deprecated in the documentation?\n\nIn [1], Junio seems to be of the opinion that we can't rid ourselves of\nit. But yeah, I suppose we could still add something to gently get the\nreader to skip that particular paragraph and learn some other diff\nsyntax or some completely different part of Git instead. The word\n\"deprecated\" seems to mean \"old-school\" to some and \"slated for removal\"\nto others. Maybe something along the lines of \"kept for backwards\ncompatibility to old habits\".\n\n> I anticipate\n> objections because it's not possible to omit `HEAD` without using\n> the two-dot form.\n\nI always just type \"HEAD\". With tab-completion, I find it just as easy\nto go \"H\" as ..\".\n\nMartin\n\n[1] https://github.blog/2020-04-07-celebrating-15-years-of-git-an-interview-with-git-maintainer-junio-hamano/#if-you-had-a-magic-wand-what-part-of-git-would-you-fix-or-change\n"},{"id":"401571","messageId":"xmqqeepdlcme.fsf@gitster.c.googlers.com","threadId":"53849","inReplyTo":"CAPx1Gve7Sy5BUdRztVoVNVZgdqm14dvD=36eYzLPed5YMQeMEQ@mail.gmail.com","subject":"Re: [PATCH 2/2] git-diff.txt: reorder possible usages","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-07-15T02:45:45Z","receivedAt":"2020-07-15T02:45:52Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Chris Torek writes:\n\n> On Mon, Jul 13, 2020 at 12:10 PM Martin Ågren wrote:\n>> It then goes on to say that \"all of the in the above\n>> description, except in the last two forms that use '..' notations, can\n>> be any \". The \"last two\" actually refers to 6 and 8. This got out\n>> of sync in commit b7e10b2ca2 (\"Documentation: usage for diff combined\n>> commits\", 2020-06-12) which added item 7 to the mix.\n>\n> Moving this down (as you do in this patch) is the right thing to do,\n> but I'll note that formally, the word \"that\" in \"forms that use ...\" is\n> part of a restrictive clause, so it means \"find the last two examples\n> that use dots\". (In American English at least, the unrestrictive version\n> would be set off with commas, and use \"which\" instead of \"that\".)\n\nYes, the proposed patch is an improvement, but I agree that \"find\nthe last two that use dots\" was indeed what I meant when I wrote\n0c783f66 (Documentation/git-diff: A..B and A...B cannot take\ntree-ishes, 2007-08-28).\n\nBut upon reading it again now, I am not sure it makes sense in the\nfirst place.\n\n git diff seen^^{tree}..seen^{tree}\n\nuses (not commit) in the form that uses '..' notation, and it\njust works fine. What does require commit because it depends on\nhaving a history to compute merge base between two objects given\nfrom the command line is the form that uses '...' notation.\n\n git diff seen^1...seen^2\n\nwould be \"what did the side branch merged at the tip of seen do\nsince it forked?\" and should look similar to \"git diff seen^ seen\",\nbut it cannot use tree objects for obvious reasons\n\n git diff seen^1^{tree}...seen^2^{tree}\n\n>> An added bonus of this commit is that we're trying to steer users away\n>> from `git diff ..` and moving it further down probably\n>> doesn't hurt.\n>\n> Q: Just how hard should we try? In particular, would it be good to mark\n> the two-dot form as deprecated in the documentation? I anticipate\n> objections because it's not possible to omit `HEAD` without using\n> the two-dot form.\n\nI am not sure why it is so important to be able to omit HEAD in the\nfirst place. I do not think using two-dot form is an offence severe\nenough to deserve an extra warning or deprecation notice, but using\nthe \"range\" notation when you meant two endpoints is a notation that\nconfuses uninitiated needlessly and showing it to new people is a\ndisservice. \"This notation does not make logical sense, but we keep\nusing it as users, and we keep accepting it as tool makers, purely\nfor convenience\" has been and will be the attitude I'd take towards\nthe \"git diff A..B\" syntax---it was a mistake we made when we were\nstill young ;-)\n\ncf. https://bit.ly/3eBcyZa\n"}]}