Marc Branchaud [off-list ref] writes:
quoted
+The '{caret}' (caret) notation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To exclude commits reachable from a commit, a prefix '{caret}'
notation is used. E.g. '{caret}r1 r2' means commits reachable
from 'r2' but exclude the ones reachable from 'r1'.
All of these headings render poorly in the manpage, at least for me
(Ubuntu 16.04). Only the first word appears in bold; the '-quoted
text is not bold but underlined, and the rest of the header is plain.
Also, I think calling this "The ^ notation" is confusing, because
there's already an earlier paragraph on the "<rev>^" syntax.
Maybe we don't need a header here? I only suggest that because I'm
having trouble coming up with a nice alternative. "Commit Exclusion"?
Thanks for pointing out the potential confusion between ^X (exclude
reachable), and X^ (the first parent). Commit exclusion is probably
a good heading.
quoted
-This set operation appears so often that there is a shorthand
+The '..' (two-dot) range notation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Perhaps "Range notation", to mirror the capitalization of "Symmetric
Difference" in the next header?
quoted
...
+The '...' (three dot) Symmetric Difference notation
This uses a strange capitalization rule. s/notation/Notation/
perhaps? The same comment for "Additional Shothand notation" below.
quoted
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A similar notation 'r1\...r2' is called symmetric difference
of 'r1' and 'r2' and is defined as
'r1 r2 --not $(git merge-base --all r1 r2)'.
It is the set of commits that are reachable from either one of
'r1' (Left side) or 'r2' (Right side) but not from both.
-In these two shorthands, you can omit one end and let it default to HEAD.
+In these two shorthand notations, you can omit one end and let it default to HEAD.
For example, 'origin..' is a shorthand for 'origin..HEAD' and asks "What
did I do since I forked from the origin branch?" Similarly, '..origin'
is a shorthand for 'HEAD..origin' and asks "What did the origin do since
I forked from them?" Note that '..' would mean 'HEAD..HEAD' which is an
empty range that is both reachable and unreachable from HEAD.
Unfortunately the new headings make it appear that this paragraph is
exclusively part of the '...' notation section. Folks reading the
..' section are likely to skip it.
I like the examples, though. I think it would be worthwhile to remove
this paragraph and fold it explicitly into the '..' and '...' notation
sections.
An alternative would be to have
- Dotted range notations
- Two-dot notation
- Three-dot notation
which would help make it stand out that defaulting is common
characteristics between .. and ... notations. But I can imagine
that your "with slight duplication" variant below would work well,
too.
So add something like this to the '..' section (only the first
sentence here is new):
Either r1 or r2 can be omitted, in which case HEAD is used as
the default. For example, 'origin..' is a shorthand for
'origin..HEAD' and asks "What did I do since I forked from the
origin branch?" Similarly, '..origin' is a shorthand for
'HEAD..origin' and asks "What did the origin do since I forked
from them?" Note that '..' would mean 'HEAD..HEAD' which is an
empty range that is both reachable and unreachable from HEAD.
And also, add the same first sentence and a different example to the
...' section. Something like this:
Either r1 or r2 can be omitted, in which case HEAD is used as
the default. For example, 'origin...' is a shorthand for
'origin...HEAD' and asks "What have I and origin both done
since I forked from the origin branch?" Note that 'origin...'
and '...origin' ask the same question.
quoted
+Additional '{caret}' Shorthand notations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.
I think descriptions of <rev>^@ and <rev>^! should live under the main
description of <rev>^. That part already describes the numeric
suffix, so describing a couple of special suffixes there seems like a
natural fit.
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).
From: "Junio C Hamano" <redacted>
Marc Branchaud [off-list ref] writes:
quoted
quoted
+The '{caret}' (caret) notation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To exclude commits reachable from a commit, a prefix '{caret}'
notation is used. E.g. '{caret}r1 r2' means commits reachable
from 'r2' but exclude the ones reachable from 'r1'.
All of these headings render poorly in the manpage, at least for me
(Ubuntu 16.04). Only the first word appears in bold; the '-quoted
text is not bold but underlined, and the rest of the header is plain.
Also, I think calling this "The ^ notation" is confusing, because
there's already an earlier paragraph on the "<rev>^" syntax.
Maybe we don't need a header here? I only suggest that because I'm
having trouble coming up with a nice alternative. "Commit Exclusion"?
Thanks for pointing out the potential confusion between ^X (exclude
reachable), and X^ (the first parent). Commit exclusion is probably
a good heading.
OK - I'll see about incorporating that.
quoted
quoted
-This set operation appears so often that there is a shorthand
+The '..' (two-dot) range notation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Perhaps "Range notation", to mirror the capitalization of "Symmetric
Difference" in the next header?
quoted
...
+The '...' (three dot) Symmetric Difference notation
This uses a strange capitalization rule. s/notation/Notation/
perhaps? The same comment for "Additional Shothand notation" below.
I'd just capitalised the specific term. Will change.
quoted
quoted
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A similar notation 'r1\...r2' is called symmetric difference
of 'r1' and 'r2' and is defined as
'r1 r2 --not $(git merge-base --all r1 r2)'.
It is the set of commits that are reachable from either one of
'r1' (Left side) or 'r2' (Right side) but not from both.
-In these two shorthands, you can omit one end and let it default to
HEAD.
+In these two shorthand notations, you can omit one end and let it
default to HEAD.
For example, 'origin..' is a shorthand for 'origin..HEAD' and asks
"What
did I do since I forked from the origin branch?" Similarly,
'..origin'
is a shorthand for 'HEAD..origin' and asks "What did the origin do
since
I forked from them?" Note that '..' would mean 'HEAD..HEAD' which is
an
empty range that is both reachable and unreachable from HEAD.
Unfortunately the new headings make it appear that this paragraph is
exclusively part of the '...' notation section. Folks reading the
..' section are likely to skip it.
I like the examples, though. I think it would be worthwhile to remove
this paragraph and fold it explicitly into the '..' and '...' notation
sections.
An alternative would be to have
- Dotted range notations
- Two-dot notation
- Three-dot notation
which would help make it stand out that defaulting is common
characteristics between .. and ... notations. But I can imagine
that your "with slight duplication" variant below would work well,
too.
I'll look into that.
quoted
So add something like this to the '..' section (only the first
sentence here is new):
Either r1 or r2 can be omitted, in which case HEAD is used as
the default. For example, 'origin..' is a shorthand for
'origin..HEAD' and asks "What did I do since I forked from the
origin branch?" Similarly, '..origin' is a shorthand for
'HEAD..origin' and asks "What did the origin do since I forked
from them?" Note that '..' would mean 'HEAD..HEAD' which is an
empty range that is both reachable and unreachable from HEAD.
And also, add the same first sentence and a different example to the
...' section. Something like this:
Either r1 or r2 can be omitted, in which case HEAD is used as
the default. For example, 'origin...' is a shorthand for
'origin...HEAD' and asks "What have I and origin both done
since I forked from the origin branch?" Note that 'origin...'
and '...origin' ask the same question.
quoted
quoted
+Additional '{caret}' Shorthand notations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.
I think descriptions of <rev>^@ and <rev>^! should live under the main
description of <rev>^. That part already describes the numeric
suffix, so describing a couple of special suffixes there seems like a
natural fit.
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 undesrtand from the description...
--
Philip
W dniu 2016-07-13 o 00:11, Philip Oakley pisze:
From: "Junio C Hamano" <redacted>
[...]
quoted
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
--
Jakub Narębski
From: "Jakub Narębski" <redacted>
W dniu 2016-07-13 o 00:11, Philip Oakley pisze:
quoted
From: "Junio C Hamano" <redacted>
[...]
quoted
quoted
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