git@vger.kernel.org mailing list mirror (one of many)
 help / color / mirror / code / Atom feed
From: Junio C Hamano <gitster@pobox.com>
To: Marc Branchaud <marcnarc@xiplink.com>
Cc: Philip Oakley <philipoakley@iee.org>,
	GitList <git@vger.kernel.org>, Jeff King <peff@peff.net>
Subject: Re: [PATCH v3 4/8] doc: give headings for the two and three dot notations
Date: Tue, 12 Jul 2016 10:04:50 -0700	[thread overview]
Message-ID: <xmqqwpkq6b4d.fsf@gitster.mtv.corp.google.com> (raw)
In-Reply-To: <5784F43E.3080400@xiplink.com> (Marc Branchaud's message of "Tue, 12 Jul 2016 09:44:30 -0400")

Marc Branchaud <marcnarc@xiplink.com> 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).


  reply	other threads:[~2016-07-12 17:04 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 [this message]
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
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=xmqqwpkq6b4d.fsf@gitster.mtv.corp.google.com \
    --to=gitster@pobox.com \
    --cc=git@vger.kernel.org \
    --cc=marcnarc@xiplink.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).