git@vger.kernel.org mailing list mirror (one of many)
 help / color / mirror / code / Atom feed
From: Marc Branchaud <marcnarc@xiplink.com>
To: Philip Oakley <philipoakley@iee.org>, GitList <git@vger.kernel.org>
Cc: Junio C Hamano <gitster@pobox.com>, Jeff King <peff@peff.net>,
	Jakub Narebski <jnareb@gmail.com>
Subject: Re: [PATCH v4 4/8] doc: give headings for the two and three dot notations
Date: Thu, 21 Jul 2016 17:20:23 -0400	[thread overview]
Message-ID: <57913C97.1030001@xiplink.com> (raw)
In-Reply-To: <9B0B8E2D61D34BFEB8FC3F30EB23437C@PhilipOakley>

On 2016-07-21 03:54 PM, Philip Oakley wrote:
> From: "Marc Branchaud" <marcnarc@xiplink.com>
>> On 2016-07-20 05:10 PM, Philip Oakley wrote:
>>> While there, also break out the other shorthand notations and
>>> add a title for the revision range summary (which also appears
>>> in git-rev-parse, so keep it mixed case).
>>>
>>> Signed-off-by: Philip Oakley <philipoakley@iee.org>
>>> ---
>>>   Documentation/revisions.txt | 58
>>> ++++++++++++++++++++++++++++-----------------
>>>   1 file changed, 36 insertions(+), 22 deletions(-)
>>>
>>> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
>>> index 6e9cd41..5b37283 100644
>>> --- a/Documentation/revisions.txt
>>> +++ b/Documentation/revisions.txt
>>> @@ -242,35 +242,49 @@ specifying a single revision with the notation
>>> described in the
>>>   previous section means the set of commits reachable from that
>>>   commit, following the commit ancestry chain.
>>>
>>> -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'.
>>> -
>>> -This set operation appears so often that there is a shorthand
>>> -for it.  When you have two commits 'r1' and 'r2' (named according
>>> -to the syntax explained in SPECIFYING REVISIONS above), you can ask
>>> -for commits that are reachable from r2 excluding those that are
>>> reachable
>>> -from r1 by '{caret}r1 r2' and it can be written as 'r1..r2'.
>>> -
>>> -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.
>>> +Commit Exclusions
>>> +~~~~~~~~~~~~~~~~~
>>> +
>>> +'{caret}<rev>' (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'.
>>> +
>>> +Dotted Range Notations
>>> +~~~~~~~~~~~~~~~~~~~~~~
>>> +
>>> +The '..' (two-dot) Range Notation::
>>> + The '{caret}r1 r2' set operation appears so often that there is a
>>> shorthand
>>> + for it.  When you have two commits 'r1' and 'r2' (named according
>>> + to the syntax explained in SPECIFYING REVISIONS above), you can ask
>>> + for commits that are reachable from r2 excluding those that are
>>> reachable
>>> + from r1 by '{caret}r1 r2' and it can be written as 'r1..r2'.
>>> +
>>> +The '...' (three dot) Symmetric Difference Notation::
>>> + A similar notation 'r1\...r2' is called symmetric difference
>>
>> s/called/called the/
>
> The wording is the original ;-) Can change.
>
>>
>>> + 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 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.
>>>
>>> -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.
>>> +Special '<rev>{caret}' Shorthand Notations
>>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>>
>> Sorry, but this header also does not render properly in the man page.
>> Maybe just "Special {caret} Shorthand Notations"?  (But read on!)
>
> rendered fine on the MYS2 man invocation - I had had to add the <rev>
> prefix to the quoted title to make it work.
>
> What went wrong for you? (I'll read on)

Only the word "Special" is emphasized (in bold).  The rest of the header 
is plain.

I'm using asciidoc 8.6.9, so I'm likely suffering from the bug Peff 
identified.

>>
>>> +Two other shorthands exist, particularly useful for merge commits, is
>>> +for naming a set that is formed by a commit and its parent commits.
>>>
>>> -To summarize:
>>> +The 'r1{caret}@' notation means all parents of 'r1'.
>>> +
>>> +'r1{caret}!' includes commit 'r1' but excludes all of its parents.
>>
>> My immediate thought upon reading this is "Why not just use 'r1'?"  I
>> think the answer is "This truncates the range."  So, for example, "git
>> log r1" shows you r1 and its ancestors, while "git log r1^!" only
>> shows you r1.  I think you should add this example, or something similar.
>>
>
> I'd also asked that question in one of my replies earlier $gmane/299849.
> I was then able to determine that it was a width wide 'range' covering
> multi-parent situations.

Obviously, I see it more an anti-range.  You're never going to get more 
than a single commit with this notation.

> Identifying an example could be good if it was succinct and explanatory.

What do you think of my example?

> $ git rev-parse 6c71a849^!
>> But, really, this means that the notation is another "Commit
>> Exclusion" and properly belongs in that section.
>
> I think it's bigger than that.
>>
>> That makes this "Special Notations" section rather thin.  I suggest
>> moving a slightly expanded <rev>^@ description to a small subsection
>> just before Commit Exclusions, and deleting the Special Notations
>> section altogether. So add something like this:
>>
>> Commit Parents
>> ~~~~~~~~~~~~~~
>
> It's a bit better, but I'm still not sure it really tells the story,
> maybe "Handling Commit Parent(s)", with that subtle extra emphasis!

"Specifying Commit Parents"?  Any of these work for me, really.

>>
>> '<rev>{caret}@' Notation::
>> The 'r1{caret}@' notation means all parents of 'r1',
>> excluding 'r1' itself.
>>
>> This smoothly re-introduces the notion of parents for readers who
>> skipped to this section, and helps them make sense of the <rev>^!
>> notation.
>>
>> Plus there's no longer anything "special" about any of the syntax.
>>
>>> +
>>> +Revision Range Summary
>>> +----------------------
>>
>> Sorry, but the man page renders this in all caps.  I really think you
>> should use ~~~~~~~~~ here.
>
> Yes, the man page formating is annoying relative to the web page
> formatting which it has to be compared against.
>
> I felt that it was at a higher level than the other sub-headings, and
> that using mixed case did work well on the html (the Git for Windows
> standard).

IMHO it has to look like it's part of the SPECIFYING RANGES section.  It 
need not be higher than the other subsections though.

> At the moment I'm minded to keep it as is unless others chime in.

I'll bow to the will of the majority.

>>
>> M.
>>
> I'll be away till mid next week.

As will I!

		M.


  reply	other threads:[~2016-07-21 21:20 UTC|newest]

Thread overview: 107+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2016-06-22  7:25 name for A..B ranges? Philip Oakley
2016-06-24 16:09 ` Jeff King
2016-06-24 16:44   ` Junio C Hamano
2016-06-25 13:50     ` Philip Oakley
2016-06-25 16:46       ` [PATCH 0/2] " Philip Oakley
2016-06-25 16:46         ` [PATCH 1/2] doc: use 'symmetric difference' consistently Philip Oakley
2016-06-25 16:46         ` [PATCH 2/2] doc: give headings for the two and three dot notations Philip Oakley
2016-06-25 18:47         ` [PATCH] doc: show the actual left, right, and boundary marks Philip Oakley
2016-06-30 20:25         ` [PATCH v2 0/4] Name for A..B ranges? Philip Oakley
2016-06-30 20:25           ` [PATCH v2 1/4] doc: use 'symmetric difference' consistently Philip Oakley
2016-06-30 20:25           ` [PATCH v2 2/4] doc: show the actual left, right, and boundary marks Philip Oakley
2016-06-30 20:25           ` [PATCH v2 3/4] doc: give headings for the two and three dot notations Philip Oakley
2016-06-30 20:25           ` [PATCH v2 4/4] doc: clarify that `^r1` will exclude `r1` itself Philip Oakley
2016-07-01 21:16             ` Junio C Hamano
2016-07-01 22:08               ` Philip Oakley
2016-07-01 22:14                 ` Junio C Hamano
2016-07-01 23:01                   ` Junio C Hamano
2016-07-10 21:17                     ` Philip Oakley
2016-07-01 21:27           ` [PATCH v2 0/4] Name for A..B ranges? Junio C Hamano
2016-07-11 20:25           ` [PATCH v3 0/8] " Philip Oakley
2016-07-11 20:25             ` [PATCH v3 1/8] doc: use 'symmetric difference' consistently Philip Oakley
2016-07-11 20:25             ` [PATCH v3 2/8] doc: revisions - name the Left and Right sides Philip Oakley
2016-07-12 16:47               ` Junio C Hamano
2016-07-12 21:47                 ` Philip Oakley
2016-07-11 20:25             ` [PATCH v3 3/8] doc: show the actual left, right, and boundary marks Philip Oakley
2016-07-11 20:25             ` [PATCH v3 4/8] doc: give headings for the two and three dot notations Philip Oakley
2016-07-12 13:44               ` Marc Branchaud
2016-07-12 17:04                 ` Junio C Hamano
2016-07-12 22:11                   ` Philip Oakley
2016-07-19 16:03                     ` Jakub Narębski
2016-07-19 19:15                       ` Philip Oakley
2016-07-12 21:41                 ` Philip Oakley
2016-07-12 22:12                   ` Jeff King
2016-07-11 20:25             ` [PATCH v3 5/8] doc: gitrevisions - use 'reachable' in page description Philip Oakley
2016-07-11 20:25             ` [PATCH v3 6/8] doc: gitrevisions - clarify 'latter case' is revision walk Philip Oakley
2016-07-11 20:25             ` [PATCH v3 7/8] doc: revisions - define `reachable` Philip Oakley
2016-07-12 13:48               ` Marc Branchaud
2016-07-12 21:44                 ` Philip Oakley
2016-07-11 20:25             ` [PATCH v3 8/8] doc: revisions - clarify reachability examples Philip Oakley
2016-07-12 19:29             ` [PATCH v3 0/8] Name for A..B ranges? Junio C Hamano
2016-07-12 22:29               ` Philip Oakley
2016-07-20 21:09             ` [PATCH v4 " Philip Oakley
2016-07-20 21:10               ` [PATCH v4 1/8] doc: use 'symmetric difference' consistently Philip Oakley
2016-07-20 21:10               ` [PATCH v4 2/8] doc: revisions - name the left and right sides Philip Oakley
2016-07-20 21:10               ` [PATCH v4 3/8] doc: show the actual left, right, and boundary marks Philip Oakley
2016-07-20 21:10               ` [PATCH v4 4/8] doc: give headings for the two and three dot notations Philip Oakley
2016-07-21 14:42                 ` Marc Branchaud
2016-07-21 19:54                   ` Philip Oakley
2016-07-21 21:20                     ` Marc Branchaud [this message]
2016-07-22 22:46                 ` Junio C Hamano
2016-07-20 21:10               ` [PATCH v4 5/8] doc: gitrevisions - use 'reachable' in page description Philip Oakley
2016-07-20 21:10               ` [PATCH v4 6/8] doc: gitrevisions - clarify 'latter case' is revision walk Philip Oakley
2016-07-20 21:10               ` [PATCH v4 7/8] doc: revisions - define `reachable` Philip Oakley
2016-07-20 21:10               ` [PATCH v4 8/8] doc: revisions - clarify reachability examples Philip Oakley
2016-07-20 22:22               ` [PATCH v4 0/8] Name for A..B ranges? Junio C Hamano
2016-08-11 21:50               ` [PATCH v5 00/12] Update git revisions Philip Oakley
2016-08-11 21:50                 ` [PATCH v5 01/12] doc: use 'symmetric difference' consistently Philip Oakley
2016-08-26 11:33                   ` Jakub Narębski
2016-08-26 16:09                     ` Junio C Hamano
2016-08-11 22:32                 ` [PATCH v5 00/12] Update git revisions Philip Oakley
2016-08-12 23:45                 ` [PATCH v6 " Philip Oakley
2016-08-12 23:45                   ` [PATCH v6 05/12] doc: revisions: extra clarification of <rev>^! notation effects Philip Oakley
2016-08-12 23:45                   ` [PATCH v6 06/12] doc: revisions: single vs multi-parent notation comparison Philip Oakley
2016-08-26 15:30                     ` Jakub Narębski
2016-08-26 16:19                       ` Junio C Hamano
2016-08-12 23:45                   ` [PATCH v6 11/12] doc: revisions: show revision expansion in examples Philip Oakley
2016-08-12 23:45                   ` [PATCH v6 12/12] doc: revisions: sort examples and fix alignment of the unchanged Philip Oakley
2016-08-15 14:30                   ` [PATCH v6 00/12] Update git revisions Marc Branchaud
2016-08-15 15:00                     ` Philip Oakley
2016-08-15 16:55                       ` BUG: indent-with-non-tab always on (was: Re: [PATCH v6 00/12] Update git revisions) Marc Branchaud
2016-08-15 17:54                         ` BUG: indent-with-non-tab always on Marc Branchaud
2016-08-15 17:06                     ` [PATCH v6 00/12] Update git revisions Junio C Hamano
2016-08-31 16:22                   ` Junio C Hamano
2016-08-11 23:03               ` [PATCH v5 " Philip Oakley
2016-08-11 23:03                 ` [PATCH v5 01/12] doc: use 'symmetric difference' consistently Philip Oakley
2016-08-12  7:07               ` [PATCH v5 00/12] Update git revisions Philip Oakley
2016-08-12  7:07                 ` [PATCH v5 01/12] doc: use 'symmetric difference' consistently Philip Oakley
2016-08-12  7:07                 ` [PATCH v5 02/12] doc: revisions - name the left and right sides Philip Oakley
2016-08-12  7:07                 ` [PATCH v5 03/12] doc: show the actual left, right, and boundary marks Philip Oakley
2016-08-12  7:07                 ` [PATCH v5 04/12] doc: revisions: give headings for the two and three dot notations Philip Oakley
2016-08-12  7:10                   ` Jeff King
2016-08-12 14:37                   ` Marc Branchaud
2016-08-12  7:07                 ` [PATCH v5 05/12] doc: revisions: extra clarification of <rev>^! notation effects Philip Oakley
2016-08-12 14:39                   ` Marc Branchaud
2016-08-12 22:17                     ` Philip Oakley
2016-08-12  7:07                 ` [PATCH v5 06/12] doc: revisions: single vs multi-parent notation comparison Philip Oakley
2016-08-12 14:40                   ` Marc Branchaud
2016-08-12 22:23                     ` Philip Oakley
2016-08-12  7:07                 ` [PATCH v5 07/12] doc: gitrevisions - use 'reachable' in page description Philip Oakley
2016-08-12  7:07                 ` [PATCH v5 08/12] doc: gitrevisions - clarify 'latter case' is revision walk Philip Oakley
2016-08-12  7:07                 ` [PATCH v5 09/12] doc: revisions - define `reachable` Philip Oakley
2016-08-28 13:01                   ` Jakub Narębski
2016-08-29 13:21                     ` Philip Oakley
2016-08-29 14:43                       ` Jakub Narębski
2016-08-29 19:27                         ` Philip Oakley
2016-08-12  7:07                 ` [PATCH v5 10/12] doc: revisions - clarify reachability examples Philip Oakley
2016-08-12  7:07                 ` [PATCH v5 11/12] doc: revisions: show revision expansion in examples Philip Oakley
2016-08-12 15:22                   ` Marc Branchaud
2016-08-12 22:45                     ` Philip Oakley
2016-08-12  7:07                 ` [PATCH v5 12/12] doc: revisions: sort examples and fix alignment of the unchanged Philip Oakley
2016-08-12 15:28                 ` [PATCH v5 00/12] Update git revisions Marc Branchaud
2016-08-12 19:20                   ` Philip Oakley
2016-08-12 21:27                     ` Junio C Hamano
2016-06-25 19:49       ` name for A..B ranges? Junio C Hamano
2016-06-27 13:37         ` Philip Oakley
2016-06-27 15:08           ` Junio C Hamano
2016-06-27 15:39             ` Philip Oakley

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: http://vger.kernel.org/majordomo-info.html

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=57913C97.1030001@xiplink.com \
    --to=marcnarc@xiplink.com \
    --cc=git@vger.kernel.org \
    --cc=gitster@pobox.com \
    --cc=jnareb@gmail.com \
    --cc=peff@peff.net \
    --cc=philipoakley@iee.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://80x24.org/mirrors/git.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).