Junio C Hamano venit, vidit, dixit 05.08.2009 18:42:
> Michael J Gruber <git@xxxxxxxxxxxxxxxxxxxx> writes:
>
>> 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
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html