[PATCH] Improve revisions.txt

[PATCH] Improve revisions.txt

[Max Horn]

One section talked about <name> when only <refname> was defined.
And the description for r1^! was incorrect, talking about "parents"
(which I understand as meaning direct parent commits),
when really all ancestors were meant.
Finally I added a few more examples (in particular one for "B..C")
that helped me understand the whole thing.

Signed-off-by: Max Horn <max@quendi.de>
---
 Documentation/revisions.txt |   20 ++++++++++++--------
 1 files changed, 12 insertions(+), 8 deletions(-)

diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index 1725661..b452265 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt
@@ -24,22 +24,22 @@ blobs contained in a commit.
   object referenced by 'refs/heads/master'.  If you
   happen to have both 'heads/master' and 'tags/master', you can
   explicitly say 'heads/master' to tell git which one you mean.
-  When ambiguous, a '<name>' is disambiguated by taking the
+  When ambiguous, a '<refname>' is disambiguated by taking the
   first match in the following rules:
 
-  . If '$GIT_DIR/<name>' exists, that is what you mean (this is usually
+  . If '$GIT_DIR/<refname>' exists, that is what you mean (this is usually
     useful only for 'HEAD', 'FETCH_HEAD', 'ORIG_HEAD', 'MERGE_HEAD'
     and 'CHERRY_PICK_HEAD');
 
-  . otherwise, 'refs/<name>' if it exists;
+  . otherwise, 'refs/<refname>' if it exists;
 
   . otherwise, 'refs/tags/<refname>' if it exists;
 
-  . otherwise, 'refs/heads/<name>' if it exists;
+  . otherwise, 'refs/heads/<refname>' if it exists;
 
-  . otherwise, 'refs/remotes/<name>' if it exists;
+  . otherwise, 'refs/remotes/<refname>' if it exists;
 
-  . otherwise, 'refs/remotes/<name>/HEAD' if it exists.
+  . otherwise, 'refs/remotes/<refname>/HEAD' if it exists.
 +
 'HEAD' names the commit on which you based the changes in the working tree.
 'FETCH_HEAD' records the branch which you fetched from a remote repository
@@ -215,8 +215,9 @@ It is the set of commits that are reachable from either one of
 
 Two other shorthands for naming a set that is formed by a commit
 and its parent commits exist.  The 'r1{caret}@' notation means all
-parents of 'r1'.  'r1{caret}!' includes commit 'r1' but excludes
-all of its parents.
+commits reachable from 'r1' except for 'r1' itself, i.e. all ancestors
+of 'r1' are included. In contrast to this, 'r1{caret}!' includes commit
+'r1' but excludes all of its ancestors.
 
 Here are a handful of examples:
 
@@ -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
-- 
1.7.7.5 (Apple Git-26)

Re: [PATCH] Improve revisions.txt

[Junio C Hamano]

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

[PATCH 1/2] Make <refname> documentation more consistent.

[Max Horn]

Formerly, the documentation for <refname> would occasionally say
<name> instead of <refname>. Now it uniformly uses <refname>.

Signed-off-by: Max Horn <max@quendi.de>
---
 Documentation/revisions.txt | 12 ++++++------
 1 Datei geändert, 6 Zeilen hinzugefügt(+), 6 Zeilen entfernt(-)

diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index 1725661..f4f6f28 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt
@@ -24,22 +24,22 @@ blobs contained in a commit.
   object referenced by 'refs/heads/master'.  If you
   happen to have both 'heads/master' and 'tags/master', you can
   explicitly say 'heads/master' to tell git which one you mean.
-  When ambiguous, a '<name>' is disambiguated by taking the
+  When ambiguous, a '<refname>' is disambiguated by taking the
   first match in the following rules:
 
-  . If '$GIT_DIR/<name>' exists, that is what you mean (this is usually
+  . If '$GIT_DIR/<refname>' exists, that is what you mean (this is usually
     useful only for 'HEAD', 'FETCH_HEAD', 'ORIG_HEAD', 'MERGE_HEAD'
     and 'CHERRY_PICK_HEAD');
 
-  . otherwise, 'refs/<name>' if it exists;
+  . otherwise, 'refs/<refname>' if it exists;
 
   . otherwise, 'refs/tags/<refname>' if it exists;
 
-  . otherwise, 'refs/heads/<name>' if it exists;
+  . otherwise, 'refs/heads/<refname>' if it exists;
 
-  . otherwise, 'refs/remotes/<name>' if it exists;
+  . otherwise, 'refs/remotes/<refname>' if it exists;
 
-  . otherwise, 'refs/remotes/<name>/HEAD' if it exists.
+  . otherwise, 'refs/remotes/<refname>/HEAD' if it exists.
 +
 'HEAD' names the commit on which you based the changes in the working tree.
 'FETCH_HEAD' records the branch which you fetched from a remote repository
-- 
1.7.11.1.145.g4722b29.dirty

[PATCH 2/2] Document rev^! and rev^@ as revision specifiers

[Max Horn]

Previously, the rev^! and rev^@ syntax were only described in the
SPECIFYING RANGES section of revisions.txt, making it a bit harder to
find information about it. Moreover, that description was slightly
confusing as it described the technical definition of rev^! and rev^@
without making it completely clear what the end effect was.
This patch attempts to address this by adding dedicate entries
for rev^! and rev^@ in the SPECIFYING REVISIONS section, rewording
the existing explanation, and adding two select additional examples.

Finally, it also adds an example for the B..C range syntax, to
help illustrate how it differs from B...C.

Signed-off-by: Max Horn <max@quendi.de>
---
 Documentation/revisions.txt | 24 +++++++++++++++++++++---
 1 Datei geändert, 21 Zeilen hinzugefügt(+), 3 Zeilen entfernt(-)

diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index f4f6f28..2784298 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt
@@ -128,6 +128,20 @@ the '$GIT_DIR/refs' directory or from the '$GIT_DIR/packed-refs' file.
   it returns the youngest matching commit which is reachable from
   the '<rev>' before '{caret}'.
 
+'<rev>{caret}@', e.g. 'HEAD{caret}@'::
+  A suffix '{caret}' followed by an at sign
+  means all parents of '<rev>'.
+  This is somewhat different from the other specifiers in this
+  section in that it may refer to multiple commits at once.
+  See also the next section on SPECIFYING RANGES.
+
+'<rev>{caret}!', e.g. 'HEAD{caret}!'::
+  A suffix '{caret}' followed by an exclamation mark
+  means commit '<rev>' but forces all of its parents to be excluded. For
+  commands that deal with a single revision, this is the same as '<rev>".
+  Hence it is primarily used with commands expecting commit ranges.
+  See also the next section on SPECIFYING RANGES.
+
 ':/<text>', e.g. ':/fix nasty bug'::
   A colon, followed by a slash, followed by a text, names
   a commit whose commit message matches the specified regular expression.
@@ -214,9 +228,10 @@ It is the set of commits that are reachable from either one of
 'r1' or 'r2' but not from both.
 
 Two other shorthands for naming a set that is formed by a commit
-and its parent commits exist.  The 'r1{caret}@' notation means all
-parents of 'r1'.  'r1{caret}!' includes commit 'r1' but excludes
-all of its parents.
+and its parent commits exist.  Recall that 'r1{caret}@' means all
+parents of 'r1'. When specifying ranges, this effectively includes
+all ancestors of 'r1' but excludes 'r1' itself. In contrast to this,
+'r1{caret}!' includes commit 'r1' but excludes all of its ancestors.
 
 Here are a handful of examples:
 
@@ -224,7 +239,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
+   C^!              C
    F^! D            G H D F
-- 
1.7.11.1.145.g4722b29.dirty

Re: [PATCH 2/2] Document rev^! and rev^@ as revision specifiers

[Junio C Hamano]

Max Horn <max@quendi.de> writes:

> +'<rev>{caret}@', e.g. 'HEAD{caret}@'::
> +  A suffix '{caret}' followed by an at sign
> +  means all parents of '<rev>'.
> +  This is somewhat different from the other specifiers in this
> +  section in that it may refer to multiple commits at once.
> +  See also the next section on SPECIFYING RANGES.

Looks good.


> +'<rev>{caret}!', e.g. 'HEAD{caret}!'::
> +  A suffix '{caret}' followed by an exclamation mark
> +  means commit '<rev>' but forces all of its parents to be excluded. For
> +  commands that deal with a single revision, this is the same as '<rev>".

Is this sentence correct?  "git commit -C 'HEAD^!'" might be a
command that expects a single revision, but I do not think it is the
same as "git commit -C HEAD".

> +  Hence it is primarily used with commands expecting commit ranges.

That is correct.

Re: [PATCH 2/2] Document rev^! and rev^@ as revision specifiers

[Max Horn]

Am 06.07.2012 um 09:21 schrieb Junio C Hamano <gitster@pobox.com>:

> Max Horn <max@quendi.de> writes:
> 
>> +'<rev>{caret}@', e.g. 'HEAD{caret}@'::
>> +  A suffix '{caret}' followed by an at sign
>> +  means all parents of '<rev>'.
>> +  This is somewhat different from the other specifiers in this
>> +  section in that it may refer to multiple commits at once.
>> +  See also the next section on SPECIFYING RANGES.
> 
> Looks good.
> 
> 
>> +'<rev>{caret}!', e.g. 'HEAD{caret}!'::
>> +  A suffix '{caret}' followed by an exclamation mark
>> +  means commit '<rev>' but forces all of its parents to be excluded. For
>> +  commands that deal with a single revision, this is the same as '<rev>".
> 
> Is this sentence correct?  "git commit -C 'HEAD^!'" might be a
> command that expects a single revision, but I do not think it is the
> same as "git commit -C HEAD".

Ignoring the exact words I used for the moment, what I meant is that these two commands should be functionally equivalent. Aren't they? If not, I obviously misunderstand something, and would like to learn more, and add a better explanation.

If they are equivalent in the sense that the end results are indistinguishable,, and you just dislike the (indeed inaccurate) choice of words, how about replacing "is the same as" by "is [functionally] equivalent".


Thank you very much for your reviews,
Max


> 
>> +  Hence it is primarily used with commands expecting commit ranges.
> 
> That is correct.
> 

Re: [PATCH 2/2] Document rev^! and rev^@ as revision specifiers

[Junio C Hamano]

Max Horn <max@quendi.de> writes:

>>> +'<rev>{caret}!', e.g. 'HEAD{caret}!'::
>>> +  A suffix '{caret}' followed by an exclamation mark
>>> +  means commit '<rev>' but forces all of its parents to be excluded. For
>>> +  commands that deal with a single revision, this is the same as '<rev>".
>> 
>> Is this sentence correct?  "git commit -C 'HEAD^!'" might be a
>> command that expects a single revision, but I do not think it is the
>> same as "git commit -C HEAD".
>
> Ignoring the exact words I used for the moment, what I meant is that these two commands should be functionally equivalent. Aren't they?

No.  When a single commit is wanted HEAD^! shouldn't be used, and
they cannot be functionally equivalent.  I haven't tried but I think
"commit -C HEAD^!"  would give you a syntax error.

Re: [PATCH 2/2] Document rev^! and rev^@ as revision specifiers

[Max Horn]

> 
On 06.07.2012, at 21:18, Junio C Hamano wrote:

> Max Horn <max@quendi.de> writes:
> 
>>>> +'<rev>{caret}!', e.g. 'HEAD{caret}!'::
>>>> +  A suffix '{caret}' followed by an exclamation mark
>>>> +  means commit '<rev>' but forces all of its parents to be excluded. For
>>>> +  commands that deal with a single revision, this is the same as '<rev>".
>>> 
>>> Is this sentence correct?  "git commit -C 'HEAD^!'" might be a
>>> command that expects a single revision, but I do not think it is the
>>> same as "git commit -C HEAD".
>> 
>> Ignoring the exact words I used for the moment, what I meant is that these two commands should be functionally equivalent. Aren't they?
> 
> No.  When a single commit is wanted HEAD^! shouldn't be used, and
> they cannot be functionally equivalent.  I haven't tried but I think
> "commit -C HEAD^!"  would give you a syntax error.
> 

Indeed, it says
 fatal: could not lookup commit HEAD^!

I'll iterate over this once more.

Cheers,
Max

Re: [PATCH 2/2] Document rev^! and rev^@ as revision specifiers

[Junio C Hamano]

Max Horn <max@quendi.de> writes:

>> 
> On 06.07.2012, at 21:18, Junio C Hamano wrote:
>
>> Max Horn <max@quendi.de> writes:
>> 
>>>>> +'<rev>{caret}!', e.g. 'HEAD{caret}!'::
>>>>> +  A suffix '{caret}' followed by an exclamation mark
>>>>> +  means commit '<rev>' but forces all of its parents to be excluded. For
>>>>> +  commands that deal with a single revision, this is the same as '<rev>".
>>>> 
>>>> Is this sentence correct?  "git commit -C 'HEAD^!'" might be a
>>>> command that expects a single revision, but I do not think it is the
>>>> same as "git commit -C HEAD".
>>> 
>>> Ignoring the exact words I used for the moment, what I meant is
>>> that these two commands should be functionally
>>> equivalent. Aren't they?
>> 
>> No.  When a single commit is wanted HEAD^! shouldn't be used, and
>> they cannot be functionally equivalent.  I haven't tried but I think
>> "commit -C HEAD^!"  would give you a syntax error.
>
> Indeed, it says
>  fatal: could not lookup commit HEAD^!
>
> I'll iterate over this once more.

Let's do this instead.

-- >8 --
Subject: Enumerate revision range specifiers in the documentation

It was a bit hard to learn how <rev>^@, <rev>^! and various other
forms of range specification are used, because they were discussed
mostly in the prose part of the documentation, unlike various forms
of extended SHA-1 expressions that are listed in enumerated list.

Also add a few more examples showing use of <rev>, <rev>..<rev> and
<rev>^! forms, stolen from a patch by Max Horn.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/revisions.txt | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index f4f6f28..6506ec6 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt
@@ -218,13 +218,44 @@ and its parent commits exist.  The 'r1{caret}@' notation means all
 parents of 'r1'.  'r1{caret}!' includes commit 'r1' but excludes
 all of its parents.
 
+To summarize:
+
+'<rev>'::
+	Include commits that are reachable from (i.e. ancestors of)
+	<rev>.
+
+'{caret}<rev>'::
+	Exclude commits that are reachable from (i.e. ancestors of)
+	<rev>.
+
+'<rev1>..<rev2>'::
+	Include commits that are reachable from <rev2> but exclude
+	those that are reachable from <rev1>.
+
+'<rev1>...<rev2>'::
+	Include commits that are reachable from either <rev1> or
+	<rev2> but exclude those that are reachable from both.
+
+'<rev>{caret}@', e.g. 'HEAD{caret}@'::
+  A suffix '{caret}' followed by an at sign is the same as listing
+  all parents of '<rev>' (meaning, include anything reachable from
+  its parents, but not the commit itself).
+
+'<rev>{caret}!', e.g. 'HEAD{caret}!'::
+  A suffix '{caret}' followed by an exclamation mark is the same
+  as giving commit '<rev>' and then all its parents prefixed with
+  '{caret}' to exclude them (and their ancestors).
+
 Here are a handful of examples:
 
    D                G H D
    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
+   C^!              C
    F^! D            G H D F