From: Junio C Hamano <gitster@pobox.com>
Date: Thu, 05 Jul 2012 18:06:48 GMT
Subject: Re: [PATCH] Improve revisions.txt
Message-ID: <7vpq8aqdzb.fsf@alter.siamese.dyndns.org>
In-Reply-To: <1341506716-97920-1-git-send-email-max@quendi.de>

Max Horn <max@quendi.de> writes:

> One section talked about <name> when only <refname> was defined.

Thanks.  This is a definite improvement.

> And the description for r1^! was incorrect, talking about "parents"
> (which I understand as meaning direct parent commits),
> when really all ancestors were meant.

What makes ^! exclude "all ancestors" is that you fed it to rev-list
or log.  r1^! really means "mark r1 as interesting, but mark its
direct parents as uninteresting".  r1^@ means "r1's direct parents
are interesting".  For example, "git show -s r1^@" will show the
direct parents of r1 but not its ancestors.

While there is nothing wrong in the updated descriptin per-se
(because it is about "specifying ranges", aka "feeding these to
rev-list or log, here is what happens"), I am torn about this part
of the patch.  Perhaps ^! and ^@ may also deserve to be described as
a way to give individual revisions (not "specifying ranges")?

I dunno.

> Finally I added a few more examples (in particular one for "B..C")
> that helped me understand the whole thing.
> ...
> @@ -224,7 +225,10 @@ Here are a handful of examples:
>     D F              G H I J D F
>     ^G D             H D
>     ^D B             E I J F B
> +   B..C             C
>     B...C            G H D E B C
>     ^D B C           E I J F B C
> +   C                I J F C
>     C^@              I J F
> +   B^! C            B C
>     F^! D            G H D F