From: Philip Oakley Date: Tue, 12 Jul 2016 22:11:42 GMT Subject: Re: [PATCH v3 4/8] doc: give headings for the two and three dot notations Message-ID: In-Reply-To: From: "Junio C Hamano" > Marc Branchaud 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 "^" 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. >>> -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. > I'd just capitalised the specific term. Will change. >>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ >>> 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. > >> 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 ^@ and ^! should live under the main >> description of ^. 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. > ^ 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