Re: [PATCH v2 4/4] doc: clarify that `^r1` will exclude `r1` itself

Philip Oakley [off-list ref] writes:

Well, if you have to spell that out, you'd want to spell out r2 side
too, no?  That is,

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

On Fri, Jul 1, 2016 at 3:08 PM, Philip Oakley [off-list ref] wrote:

quoted

quoted

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

Well, you have the same inclusivity issue on the opposite end, no? Is 0..4
a range with 0,1,2,3,4? 0,1,2,3? 1,2,3,4? or 1,2,3?

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

I am not sure I agree. It all is about "is the endpoint included or not?".

From: "Junio C Hamano" <redacted>

Philip Oakley [off-list ref] writes:

quoted

Signed-off-by: Philip Oakley <redacted>
---
 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)