Re: [PATCH 2/2] Document rev^! and rev^@ as revision specifiers
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Jul 23, 2012, 19:27 UTC
- Message-ID
- <7vliial1l1.fsf@alter.siamese.dyndns.org>
- In-Reply-To
- <05708C97-7925-4E45-BA16-374FB38F54D1@quendi.de>
Max Horn <max@quendi.de> writes:
Show 26 quoted lines
>>
> 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