Marc Branchaud <marcnarc@xxxxxxxxxxx> writes:
>> +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.
>> -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?
>> ...
>> +The '...' (three dot) Symmetric Difference notation
This uses a strange capitalization rule. s/notation/Notation/
perhaps? The same comment for "Additional Shothand notation" below.
>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>> 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.
>> +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).
--
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