git@vger.kernel.org mailing list mirror (one of many)
 help / color / mirror / code / Atom feed
From: "Philip Oakley" <philipoakley@iee.org>
To: "Junio C Hamano" <gitster@pobox.com>
Cc: "GitList" <git@vger.kernel.org>, "Jeff King" <peff@peff.net>
Subject: Re: [PATCH v2 4/4] doc: clarify that `^r1` will exclude `r1` itself
Date: Fri, 1 Jul 2016 23:08:24 +0100	[thread overview]
Message-ID: <38FAE374CD2D44EC9C86167F98953271@PhilipOakley> (raw)
In-Reply-To: xmqqk2h5vz2m.fsf@gitster.mtv.corp.google.com

From: "Junio C Hamano" <gitster@pobox.com>
> Philip Oakley <philipoakley@iee.org> writes:
>
>> Signed-off-by: Philip Oakley <philipoakley@iee.org>
>> ---
>>  Documentation/revisions.txt | 2 +-
>>  1 file changed, 1 insertion(+), 1 deletion(-)
>>
>> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
>> index 131060c..87be9c4 100644
>> --- a/Documentation/revisions.txt
>> +++ b/Documentation/revisions.txt
>> @@ -246,7 +246,7 @@ 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'.
>> +from 'r2' but exclude 'r1' and those reachable from 'r1'.
>
> Well, if you have to spell that out, you'd want to spell out r2 side
> too, no?  That is,

The clarification wasn't about what "reachable" means but about inclusivity,
such as whether 0..4 would give 0,1,2,3,4 or would be 'off by one' and only
give 1,2,3,4. And in this case it's the latter.

Describing 'reachability' is a whole different kettle of fish, as you
highlight below, and would be separate from this patch.

I've certainly tripped up in the past over using an appropriate reachability
definition in r1..r2, and forgetting (*) about remote branches being in the
local graph . (*- i.e. not really understanding!)

--
Philip
(only occasional access to internet over next few days)
>
> ... means commits 'r2' and those reachable from 'r2', but
> exclude 'r1' and those reachable from 'r1'.
>
> The (sub)document has 16 grep hits of "reach(able)"; a reader who
> needs this clarification would need all of them clarified, but
> repeating "X and those reachable from X" everywhere is not a good
> way to do so.  Perhaps a separate sentence upfront that defines what
> "reachable" means is a better solution, no?
>
> Something like the attached patch may be a good starting point, but
> this leaves two forward-references of reachable in the part that
> describes ways to specify a single object (e.g. find a commit with
> this string that is reachable by X) we may need to address, perhaps
> by adding "(see below)" or something.
>
>
> Documentation/revisions.txt | 4 ++++
> 1 file changed, 4 insertions(+)
>
> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
> index 19314e3..34642b9 100644
> --- a/Documentation/revisions.txt
> +++ b/Documentation/revisions.txt
> @@ -242,6 +242,10 @@ 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.
>
> +A commit Y is said to be reachable from commit X if Y is X, or if Y
> +is reachable from any any of X's parents.  We also say "Y is an
> +ancestor of X" in such a case.
> +
> 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'.
>
> 


  reply	other threads:[~2016-07-01 22:21 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 [this message]
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
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=38FAE374CD2D44EC9C86167F98953271@PhilipOakley \
    --to=philipoakley@iee.org \
    --cc=git@vger.kernel.org \
    --cc=gitster@pobox.com \
    --cc=peff@peff.net \
    /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).