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

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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


[Index of Archives]     [Linux Kernel Development]     [Gcc Help]     [IETF Annouce]     [DCCP]     [Netdev]     [Networking]     [Security]     [V4L]     [Bugtraq]     [Yosemite]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Linux SCSI]     [Fedora Users]