Re: [PATCH v3 4/8] doc: give headings for the two and three dot notations

["Philip Oakley" <philipoakley@iee.org>]

From: "Jakub Narębski" <jnareb@gmail.com>
>W dniu 2016-07-13 o 00:11, Philip Oakley pisze:
>> From: "Junio C Hamano" <gitster@pobox.com>
> [...]
>>> I actually think this is a good place to have them described.
>>> <rev>^<number> is about specifying a single commit.  These two are
>>> not that (you can say HEAD^2^@ but you cannot say HEAD^@^2, for
>>> example).
>>
>> These two are special cases I'm not too familiar with, particularly
>> the r1^! which I didn't understand from the description...
>
> <rev>^@ is all parents of <rev>, that is
>
>  <rev>^@  ==  <rev>^1 <rev>^2 ... <rev>^<n>
>
> where <n> is number of parents commit <rev> has.
>
>
> <rev>^! is (if standalone) a single commit range, only <rev> revision.
> It is actually
>
>  <rev>^!  ==  ( <rev> --not <rev>^@ )
>
> that is, reachable from <rev> but not from any of its parents.
> Parentheses here denote that `--not` does not affect the rest of
> rev-like parameters.
>
>
> Hope that helps
> -- 

The tricky part is seeing that, rather than being a depth wise range, it's 
actually a width wise range that is designed to cover the scenarios around 
merges

e.g. $ git rev-parse 6c71a849^!
or $ git rev-parse 6c71a849^@

In the doc that I'm updating I'll add a comment that it's particulalry 
useful around merges.

Mind you I did see dscho quote it in $gmane/299738
" You can also inspect the diff of a commit, using the ^! suffix, e.g.

  git difftool -x diff origin/master~3^!

--
Philip