Re: [PATCH 2/2] git-rev-list.txt: Clarify the use of multiple revision arguments
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Aug 5, 2009, 16:42 UTC
- Message-ID
- <7vd47adxfq.fsf@alter.siamese.dyndns.org>
- In-Reply-To
- <1249459117-3853-2-git-send-email-git@drmicha.warpmail.net>
Michael J Gruber <git@drmicha.warpmail.net> writes:
Show 14 quoted lines
> 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