[PATCH 1/2] git-rev-list.txt: Correct description for multiple arguments

[PATCH 1/2] git-rev-list.txt: Correct description for multiple arguments

[Michael J Gruber]

"git rev-list A B" really lists those commits which are included in A or
B, i.e. it lists those in A and those in B. Say so, because saying
"which are included in A and B" would mean those who are in both A and
B.

Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
---
Patch against master.

The current description is simply wrong, which is why I strongly suggest this fix.
The upcoming suggests an extra paragraph for clarifying the use of multiple
revision arguments.

 Documentation/git-rev-list.txt |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt
index a765cfa..847cc7d 100644
--- a/Documentation/git-rev-list.txt
+++ b/Documentation/git-rev-list.txt
@@ -63,7 +63,7 @@ command:
 	$ git rev-list foo bar ^baz
 -----------------------------------------------------------------------
 
-means "list all the commits which are included in 'foo' and 'bar', but
+means "list all the commits which are included in 'foo' or 'bar', but
 not in 'baz'".
 
 A special notation "'<commit1>'..'<commit2>'" can be used as a
-- 
1.6.4.70.g9c084

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

[Michael J Gruber]

If one thinks of a revision as the set of commits which can be reached
from the rev, and of ^rev as the complement, then multiple arguments to
git rev-list can be neither understood as the intersection nor the union
of the individual sets.

But set language is the natural as well as logical language in which to
phrase this. So, add a paragraph which explains multiple arguments using
set language.

Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
---
While one could explain this also by describing the revision walker,
I think that and/or/union/intersection should be clearer for the average
user.

We may even want to add a paragraph which explains how one gets "A intersected B",
which is impossible to do with rev-list.

 Documentation/git-rev-list.txt |    7 +++++++
 1 files changed, 7 insertions(+), 0 deletions(-)

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}').
+
 A special notation "'<commit1>'..'<commit2>'" can be used as a
 short-hand for "{caret}'<commit1>' '<commit2>'". For example, either of
 the following may be used interchangeably:
-- 
1.6.4.70.g9c084

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

[Junio C Hamano]

Michael J Gruber <git@drmicha.warpmail.net> 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?

 Documentation/git-rev-list.txt |   22 ++++++++++++++--------
 1 files changed, 14 insertions(+), 8 deletions(-)

diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt
index a765cfa..8c1535e 100644
--- a/Documentation/git-rev-list.txt
+++ b/Documentation/git-rev-list.txt
@@ -51,20 +51,26 @@ SYNOPSIS
 DESCRIPTION
 -----------
 
-Lists commit objects in reverse chronological order starting at the
-given commit(s), taking ancestry relationship into account.  This is
-useful to produce human-readable log output.
+List commits that are reachable by following the `parent` links from the
+given commit(s), but exclude commits that are reachable from the one(s)
+given with a '{caret}' in front of them.  The output is given in reverse
+chronological order by default.
 
-Commits which are stated with a preceding '{caret}' cause listing to
-stop at that point. Their parents are implied. Thus the following
-command:
+You can think of this as a set operation.  Commits given on the command
+line form a set of commits that are reachable from any of them, and then
+commits reachable from any of the ones given with '{caret}' in front are
+subtracted from that set.  The remaining commits are what comes out in the
+command's output.  Various other options and paths parameters can be used
+to further limit the result.
+
+Thus, the following command:
 
 -----------------------------------------------------------------------
 	$ git rev-list foo bar ^baz
 -----------------------------------------------------------------------
 
-means "list all the commits which are included in 'foo' and 'bar', but
-not in 'baz'".
+means "list all the commits which are reachable from 'foo' or 'bar', but
+not from 'baz'".
 
 A special notation "'<commit1>'..'<commit2>'" can be used as a
 short-hand for "{caret}'<commit1>' '<commit2>'". For example, either of

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

[Michael J Gruber]

Junio C Hamano venit, vidit, dixit 05.08.2009 18:42:
> Michael J Gruber <git@drmicha.warpmail.net> 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