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

From: Junio C Hamano <gitster@pobox.com>
Date: Jul 12, 2016, 17:04 UTC
Message-ID: <xmqqwpkq6b4d.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <5784F43E.3080400@xiplink.com>

Marc Branchaud <marcnarc@xiplink.com> writes:

Show 16 quoted lines

>> +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.

Show 8 quoted lines

>> -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.

Show 22 quoted lines

>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>>   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.

Show 19 quoted lines

> 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.

Show 12 quoted lines

>> +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).