Re: [PATCH 2/2] git-rev-list.txt: Clarify the use of multiple revision arguments

Junio C Hamano venit, vidit, dixit 05.08.2009 18:42:

Michael J Gruber [off-list ref] writes:

quoted

diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt
index 847cc7d..40ca276 100644
--- a/Documentation/git-rev-list.txt
+++ b/Documentation/git-rev-list.txt

@@ -66,6 +66,13 @@ command:
 means "list all the commits which are included in 'foo' or 'bar', but
 not in 'baz'".
 
+So, the resulting set of commits is the union of 'foo' and 'bar',
+intersected with the complement of baz. The order of arguments is
+irrelevant: first, the union of all positive refs (those without
+'{caret}') is taken, then the result is intersected with all negative
+refs (i.e. with the complement of the union of all refs which appear
+with a preceding '{caret}').

It seems to me that the first sentence just repeats what the previous
sentence that we can see in the context with different fuzziness.

I am guessing that the reason you are patching this is because you felt
that the existing "list all the commits which are _included in_ 'foo' or
'bar', but not _in_ 'baz'" uses "be included in" without defining what it
really means (i.e. "reachable by following the ancestry").

I however find the "union of 'foo' and 'bar' intersected with the
complement of 'baz'" similarly lacking.  The sentence equates commit X
with the set of commits that are reachable from X, without explaining that
is what it is doing.

To me, this feels much worse than the original.  When you say commit X,
the reader must guess if you are talking about the single commit, or the
set of commits reachable from it by following the ancestry chain.

How about rewriting it a bit more without repeating?

Yes, I tried to be minimally invasive, which is also why I split the
patch in two (correction + addition). I really prefer your rephrased
version. Feel free to squash in/ask me to resubmit/whatever suits you.

Michael