{"thread":{"id":"20396","subject":"[PATCH 1/2] git-rev-list.txt: Correct description for multiple arguments","startedAt":"2009-08-05T07:58:36Z","lastAt":"2009-08-06T08:48:59Z","messageCount":4,"participants":["Michael J Gruber","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":2},"messages":[{"id":"119579","messageId":"1249459117-3853-1-git-send-email-git@drmicha.warpmail.net","threadId":"20396","inReplyTo":null,"subject":"[PATCH 1/2] git-rev-list.txt: Correct description for multiple arguments","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2009-08-05T07:58:36Z","receivedAt":"2009-08-05T07:58:36Z","isPatch":true,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"\"git rev-list A B\" really lists those commits which are included in A or\nB, i.e. it lists those in A and those in B. Say so, because saying\n\"which are included in A and B\" would mean those who are in both A and\nB.\n\nSigned-off-by: Michael J Gruber \n---\nPatch against master.\n\nThe current description is simply wrong, which is why I strongly suggest this fix.\nThe upcoming suggests an extra paragraph for clarifying the use of multiple\nrevision arguments.\n\n Documentation/git-rev-list.txt | 2 +-\n 1 files changed, 1 insertions(+), 1 deletions(-)\n\ndiff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt\nindex a765cfa..847cc7d 100644\n--- a/Documentation/git-rev-list.txt\n+++ b/Documentation/git-rev-list.txt\n@@ -63,7 +63,7 @@ command:\n \t$ git rev-list foo bar ^baz\n -----------------------------------------------------------------------\n \n-means \"list all the commits which are included in 'foo' and 'bar', but\n+means \"list all the commits which are included in 'foo' or 'bar', but\n not in 'baz'\".\n \n A special notation \"''..''\" can be used as a\n-- \n1.6.4.70.g9c084\n"},{"id":"119580","messageId":"1249459117-3853-2-git-send-email-git@drmicha.warpmail.net","threadId":"20396","inReplyTo":"1249459117-3853-1-git-send-email-git@drmicha.warpmail.net","subject":"[PATCH 2/2] git-rev-list.txt: Clarify the use of multiple revision arguments","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2009-08-05T07:58:37Z","receivedAt":"2009-08-05T07:58:37Z","isPatch":true,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"If one thinks of a revision as the set of commits which can be reached\nfrom the rev, and of ^rev as the complement, then multiple arguments to\ngit rev-list can be neither understood as the intersection nor the union\nof the individual sets.\n\nBut set language is the natural as well as logical language in which to\nphrase this. So, add a paragraph which explains multiple arguments using\nset language.\n\nSigned-off-by: Michael J Gruber \n---\nWhile one could explain this also by describing the revision walker,\nI think that and/or/union/intersection should be clearer for the average\nuser.\n\nWe may even want to add a paragraph which explains how one gets \"A intersected B\",\nwhich is impossible to do with rev-list.\n\n Documentation/git-rev-list.txt | 7 +++++++\n 1 files changed, 7 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt\nindex 847cc7d..40ca276 100644\n--- a/Documentation/git-rev-list.txt\n+++ b/Documentation/git-rev-list.txt\n@@ -66,6 +66,13 @@ command:\n means \"list all the commits which are included in 'foo' or 'bar', but\n not in 'baz'\".\n \n+So, the resulting set of commits is the union of 'foo' and 'bar',\n+intersected with the complement of baz. The order of arguments is\n+irrelevant: first, the union of all positive refs (those without\n+'{caret}') is taken, then the result is intersected with all negative\n+refs (i.e. with the complement of the union of all refs which appear\n+with a preceding '{caret}').\n+\n A special notation \"''..''\" can be used as a\n short-hand for \"{caret}'' ''\". For example, either of\n the following may be used interchangeably:\n-- \n1.6.4.70.g9c084\n"},{"id":"119629","messageId":"7vd47adxfq.fsf@alter.siamese.dyndns.org","threadId":"20396","inReplyTo":"1249459117-3853-2-git-send-email-git@drmicha.warpmail.net","subject":"Re: [PATCH 2/2] git-rev-list.txt: Clarify the use of multiple revision arguments","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-08-05T16:42:33Z","receivedAt":"2009-08-05T16:42:33Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Michael J Gruber writes:\n\n> diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt\n> index 847cc7d..40ca276 100644\n> --- a/Documentation/git-rev-list.txt\n> +++ b/Documentation/git-rev-list.txt\n> @@ -66,6 +66,13 @@ command:\n> means \"list all the commits which are included in 'foo' or 'bar', but\n> not in 'baz'\".\n> \n> +So, the resulting set of commits is the union of 'foo' and 'bar',\n> +intersected with the complement of baz. The order of arguments is\n> +irrelevant: first, the union of all positive refs (those without\n> +'{caret}') is taken, then the result is intersected with all negative\n> +refs (i.e. with the complement of the union of all refs which appear\n> +with a preceding '{caret}').\n\nIt seems to me that the first sentence just repeats what the previous\nsentence that we can see in the context with different fuzziness.\n\nI am guessing that the reason you are patching this is because you felt\nthat the existing \"list all the commits which are _included in_ 'foo' or\n'bar', but not _in_ 'baz'\" uses \"be included in\" without defining what it\nreally means (i.e. \"reachable by following the ancestry\").\n\nI however find the \"union of 'foo' and 'bar' intersected with the\ncomplement of 'baz'\" similarly lacking. The sentence equates commit X\nwith the set of commits that are reachable from X, without explaining that\nis what it is doing.\n\nTo me, this feels much worse than the original. When you say commit X,\nthe reader must guess if you are talking about the single commit, or the\nset of commits reachable from it by following the ancestry chain.\n\nHow about rewriting it a bit more without repeating?\n\n Documentation/git-rev-list.txt | 22 ++++++++++++++--------\n 1 files changed, 14 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt\nindex a765cfa..8c1535e 100644\n--- a/Documentation/git-rev-list.txt\n+++ b/Documentation/git-rev-list.txt\n@@ -51,20 +51,26 @@ SYNOPSIS\n DESCRIPTION\n -----------\n \n-Lists commit objects in reverse chronological order starting at the\n-given commit(s), taking ancestry relationship into account. This is\n-useful to produce human-readable log output.\n+List commits that are reachable by following the `parent` links from the\n+given commit(s), but exclude commits that are reachable from the one(s)\n+given with a '{caret}' in front of them. The output is given in reverse\n+chronological order by default.\n \n-Commits which are stated with a preceding '{caret}' cause listing to\n-stop at that point. Their parents are implied. Thus the following\n-command:\n+You can think of this as a set operation. Commits given on the command\n+line form a set of commits that are reachable from any of them, and then\n+commits reachable from any of the ones given with '{caret}' in front are\n+subtracted from that set. The remaining commits are what comes out in the\n+command's output. Various other options and paths parameters can be used\n+to further limit the result.\n+\n+Thus, the following command:\n \n -----------------------------------------------------------------------\n \t$ git rev-list foo bar ^baz\n -----------------------------------------------------------------------\n \n-means \"list all the commits which are included in 'foo' and 'bar', but\n-not in 'baz'\".\n+means \"list all the commits which are reachable from 'foo' or 'bar', but\n+not from 'baz'\".\n \n A special notation \"''..''\" can be used as a\n short-hand for \"{caret}'' ''\". For example, either of\n"},{"id":"119761","messageId":"4A7A98FB.7070104@drmicha.warpmail.net","threadId":"20396","inReplyTo":"7vd47adxfq.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH 2/2] git-rev-list.txt: Clarify the use of multiple revision arguments","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2009-08-06T08:48:59Z","receivedAt":"2009-08-06T08:48:59Z","isPatch":true,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"Junio C Hamano venit, vidit, dixit 05.08.2009 18:42:\n> Michael J Gruber writes:\n> \n>> diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt\n>> index 847cc7d..40ca276 100644\n>> --- a/Documentation/git-rev-list.txt\n>> +++ b/Documentation/git-rev-list.txt\n>> @@ -66,6 +66,13 @@ command:\n>> means \"list all the commits which are included in 'foo' or 'bar', but\n>> not in 'baz'\".\n>> \n>> +So, the resulting set of commits is the union of 'foo' and 'bar',\n>> +intersected with the complement of baz. The order of arguments is\n>> +irrelevant: first, the union of all positive refs (those without\n>> +'{caret}') is taken, then the result is intersected with all negative\n>> +refs (i.e. with the complement of the union of all refs which appear\n>> +with a preceding '{caret}').\n> \n> It seems to me that the first sentence just repeats what the previous\n> sentence that we can see in the context with different fuzziness.\n> \n> I am guessing that the reason you are patching this is because you felt\n> that the existing \"list all the commits which are _included in_ 'foo' or\n> 'bar', but not _in_ 'baz'\" uses \"be included in\" without defining what it\n> really means (i.e. \"reachable by following the ancestry\").\n> \n> I however find the \"union of 'foo' and 'bar' intersected with the\n> complement of 'baz'\" similarly lacking. The sentence equates commit X\n> with the set of commits that are reachable from X, without explaining that\n> is what it is doing.\n> \n> To me, this feels much worse than the original. When you say commit X,\n> the reader must guess if you are talking about the single commit, or the\n> set of commits reachable from it by following the ancestry chain.\n> \n> How about rewriting it a bit more without repeating?\n\nYes, I tried to be minimally invasive, which is also why I split the\npatch in two (correction + addition). I really prefer your rephrased\nversion. Feel free to squash in/ask me to resubmit/whatever suits you.\n\nMichael\n"}]}