Re: [PATCH v2 4/4] doc: clarify that `^r1` will exclude `r1` itself
From: Junio C Hamano <hidden>
Date: 2016-07-01 21:16:42
Subsystem:
documentation, the rest · Maintainers:
Jonathan Corbet, Linus Torvalds
Possibly related (same subject, not in this thread)
- 2016-07-10 · Re: [PATCH v2 4/4] doc: clarify that `^r1` will exclude `r1` itself · Philip Oakley <hidden>
- 2016-07-01 · Re: [PATCH v2 4/4] doc: clarify that `^r1` will exclude `r1` itself · Junio C Hamano <hidden>
- 2016-06-30 · [PATCH v2 4/4] doc: clarify that `^r1` will exclude `r1` itself · Philip Oakley <hidden>
Philip Oakley [off-list ref] writes:
quoted hunk
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, ... 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'.