Max Horn <max@xxxxxxxxx> writes:
>>
> On 06.07.2012, at 21:18, Junio C Hamano wrote:
>
>> Max Horn <max@xxxxxxxxx> 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@xxxxxxxxx>
---
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
--
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