Re: [PATCH v4 0/8] Name for A..B ranges?
Philip Oakley writes: > No change in the number of patches. Interdiff below. > > The patches carefully tease out the clarification of > reachability. Reachability is defined relative the ancestry chain thus > (hopefully) avoiding misunderstandings. > > The final patch updates the summary examples, and the tricky (for the > untutored reader) two dots case of a linear development where r1..r2 > excludes r1 itself. All looked sensible and each focused on a single issue and fixing it well. Done very nicely. Thanks. Will (re)queue, wait for a few days for further comments and let's merge it to 'next'. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v4 0/8] Name for A..B ranges?
This is the V4 re-roll of the po/range-doc (2016-07-01) 3 commits and its
follow on patch.
Capitalisation has been fixed.
Heading levels for man pages has been fixed.
Quoting of the caret has been fixed.
The extra width wise 'caret' shorthands now mention their applicability to
merge commits.
No change in the number of patches. Interdiff below.
The patches carefully tease out the clarification of
reachability. Reachability is defined relative the ancestry chain thus
(hopefully) avoiding misunderstandings.
The final patch updates the summary examples, and the tricky (for the
untutored reader) two dots case of a linear development where r1..r2
excludes r1 itself.
The patches can be squashed together if required.
Original discussion starts at: $gmane/297908
V1 patch series $gmane/298223
V2 patch series $gmane/298689
V3 patch series $gmane/299293
Philip Oakley (8):
doc: use 'symmetric difference' consistently
doc: revisions - name the left and right sides
doc: show the actual left, right, and boundary marks
doc: give headings for the two and three dot notations
doc: gitrevisions - use 'reachable' in page description
doc: gitrevisions - clarify 'latter case' is revision walk
doc: revisions - define `reachable`
doc: revisions - clarify reachability examples
Documentation/gitk.txt | 2 +-
Documentation/gitrevisions.txt | 6 +--
Documentation/pretty-formats.txt | 2 +-
Documentation/rev-list-options.txt | 4 +-
Documentation/revisions.txt| 83 --
5 files changed, 59 insertions(+), 38 deletions(-)
interdiff:
diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index dba4fc6..14622cc 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt
@@ -241,35 +241,38 @@ of commits, not just a single commit.
For these commands,
specifying a single revision, using the notation described in the
-previous section, means the `reachable` set of commits of the given
+previous section, means the set of commits `reachable` from the given
commit.
-A commit's reachable set is the commit itself and the commits of
+A commit's reachable set is the commit itself and the commits in
its ancestry chain.
-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 those reachable from 'r1' (i.e. 'r1' and its
-ancestors).
-
-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
-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.
+Commit Exclusions
+~
+
+'{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' (i.e. 'r1' and
+ its ancestors).
+
+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
+ 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
@@ -278,10 +281,10 @@ 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.
-Additional '{caret}' Shorthand notations
-
-Two other shorthands for naming a set that is formed by a commit
-and its parent commits exist.
+Special '{caret}' Shorthand Notations
+~~~
Re: [PATCH v3 0/8] Name for A..B ranges?
From: "Junio C Hamano" Philip Oakley writes: This is the re-roll of the po/range-doc (2016-07-01) 3 commits and its follow on patch. The series has gained additional patches following the discussions ($gmane/298790). .. The patches can be squashed together if required. Looked mostly sensible, except for a few things mentioned in the reviews by Marc (to which I mostly agree with). Thanks. I'll update in the next few days. Philip -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v3 0/8] Name for A..B ranges?
Philip Oakley writes: > This is the re-roll of the po/range-doc (2016-07-01) 3 commits and its > follow on patch. > > The series has gained additional patches following the discussions > ($gmane/298790). > > The original first 3 patches are unchanged, though 2/8 has been inserted > to name the Left and Right ranges. > > The extra four patches carefully tease out the clarification of > reachability. Reachability is defined relative the ancestry chain thus > (hopefully) avoiding misunderstandings. > > The final patch updates the summary examples, and the tricky (for the > untutored reader) two dots case of a linear development where r1..r2 > excludes r1 itself. > > The patches can be squashed together if required. Looked mostly sensible, except for a few things mentioned in the reviews by Marc (to which I mostly agree with). Thanks. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v3 0/8] Name for A..B ranges?
This is the re-roll of the po/range-doc (2016-07-01) 3 commits and its follow on patch. The series has gained additional patches following the discussions ($gmane/298790). The original first 3 patches are unchanged, though 2/8 has been inserted to name the Left and Right ranges. The extra four patches carefully tease out the clarification of reachability. Reachability is defined relative the ancestry chain thus (hopefully) avoiding misunderstandings. The final patch updates the summary examples, and the tricky (for the untutored reader) two dots case of a linear development where r1..r2 excludes r1 itself. The patches can be squashed together if required. Original discussion starts at: $gmane/297908 V1 patch series $gmane/298223 V2 patch series $gmane/298689 Philip Oakley (8): doc: use 'symmetric difference' consistently doc: revisions - name the Left and Right sides doc: show the actual left, right, and boundary marks doc: give headings for the two and three dot notations doc: gitrevisions - use 'reachable' in page description doc: gitrevisions - clarify 'latter case' is revision walk doc: revisions - define `reachable` doc: revisions - clarify reachability examples Documentation/gitk.txt | 2 +- Documentation/gitrevisions.txt | 6 ++--- Documentation/pretty-formats.txt | 2 +- Documentation/rev-list-options.txt | 4 +-- Documentation/revisions.txt| 50 ++ 5 files changed, 41 insertions(+), 23 deletions(-) -- 2.8.4.windows.1.3.ge328a54 follows from msg-ID <20160630202509.4472-1-philipoak...@iee.org> -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v2 0/4] Name for A..B ranges?
Philip Oakley writes: > This is the re-roll of the po/range-doc (2016-06-27) 3 commits > > The order is slightly re-arranged, and an additional patch clarifying > that ^r1 excludes r1 itself being added. > > The heading have been tweaked. Thanks. I think 1-3 are ready for 'next'. 4/4 may need a bit more thinking. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH v2 0/4] Name for A..B ranges?
This is the re-roll of the po/range-doc (2016-06-27) 3 commits The order is slightly re-arranged, and an additional patch clarifying that ^r1 excludes r1 itself being added. The heading have been tweaked. Discussion: $gmane/297908 previous patch series $gmane/298223 Philip Oakley (4): doc: use 'symmetric difference' consistently doc: show the actual left, right, and boundary marks doc: give headings for the two and three dot notations doc: clarify that `^r1` will exclude `r1` itself Documentation/gitk.txt | 2 +- Documentation/pretty-formats.txt | 2 +- Documentation/rev-list-options.txt | 4 ++-- Documentation/revisions.txt| 25 ++--- 4 files changed, 22 insertions(+), 11 deletions(-) -- 2.8.4.windows.1.3.ge328a54 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: name for A..B ranges?
From: "Junio C Hamano" "Philip Oakley" writes: ..., I was wondering if an alternative would be to refer to it via [use the headings of] it's notation, i.e. "the 'two-dot' range notation" (or 'syntax' is that is preferred), and the "three-dot symmetric difference notation". That's a lot more sensible pair of headings, I would think. The existing explanatory text can stand as is, but they would now have a section for readers to find. Or should I just drop this? I like the approach to separate them into clearly marked sections. I primarily was reacting to the "single-sided" which nobody would understand. -- Thanks, I'll update the patches (probably tomorrow) Philip -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: name for A..B ranges?
"Philip Oakley" writes: > ..., I was wondering > if an alternative would be to refer to it via [use the headings of] > it's notation, i.e. "the 'two-dot' range notation" (or 'syntax' is > that is preferred), and the "three-dot symmetric difference notation". That's a lot more sensible pair of headings, I would think. > The existing explanatory text can stand as is, but they would now have > a section for readers to find. > > Or should I just drop this? I like the approach to separate them into clearly marked sections. I primarily was reacting to the "single-sided" which nobody would understand. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: name for A..B ranges?
From: "Junio C Hamano" "Philip Oakley" writes: Yup, I think "range" is the commonly used word in discussions here. When inventing A...B as a new thing in addition to A..B, we called the former "symmetric difference", and what is implied by that is the latter is "asymmetric difference"; we do not say that unless we are contrasting between the two, though. I asked because the man page does indicae that it (A..B) is a special sort of revison range and "there is a shorthand for it", but then didn't have a way of naming it. I do not see "is a special sort of revision range" improved in your two patches, though. Hi Junio I'm not sure what's meant here. That patch was about ensuring that the relevant syntax notations had headings to make them more easily locatable, not to change the explanations. Knowing that A..B is merely a short-hand for ^A B is important to understand how revision ranges work (e.g. "A..B C" is not "union of A..B and C"), so I think it is worth addressing if the existing description appeared to you that it may confuse readers. I felt the explanations, once found, were OK. It was the discovery step I was hoepfully addressing. The symmetric difference is then brought in as a further similar notation. There are a number of Stackoverflow questions about the differences betwee 'two dots' and 'three dots' as well, so having a word/phrase for it could help. I was thinking that maybe "single-sided difference (two dots)" maybe one choice that is relatively neutral (or even a "two-dot range"...). When contrasting .. and ..., we have always used "asymmetric" vs "symmetric". I'd prefer to see usnot invent new phrase nobody has used, which leads to unnecessary confusion and learning burden. Rather than trying to find a complement to the previously invented "symmetric difference" name (for the section heading), I was wondering if an alternative would be to refer to it via [use the headings of] it's notation, i.e. "the 'two-dot' range notation" (or 'syntax' is that is preferred), and the "three-dot symmetric difference notation". The existing explanatory text can stand as is, but they would now have a section for readers to find. Or should I just drop this? -- Philip -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: name for A..B ranges?
"Philip Oakley" writes: >> Yup, I think "range" is the commonly used word in discussions here. >> When inventing A...B as a new thing in addition to A..B, we called >> the former "symmetric difference", and what is implied by that is >> the latter is "asymmetric difference"; we do not say that unless we >> are contrasting between the two, though. >> > I asked because the man page does indicae that it (A..B) is a special > sort of revison range and "there is a shorthand for it", but then > didn't have a way of naming it. I do not see "is a special sort of revision range" improved in your two patches, though. Knowing that A..B is merely a short-hand for ^A B is important to understand how revision ranges work (e.g. "A..B C" is not "union of A..B and C"), so I think it is worth addressing if the existing description appeared to you that it may confuse readers. > The symmetric difference is then brought in as a further similar > notation. There are a number of Stackoverflow questions about the > differences betwee 'two dots' and 'three dots' as well, so having a > word/phrase for it could help. > > I was thinking that maybe "single-sided difference (two dots)" maybe > one choice that is relatively neutral (or even a "two-dot range"...). When contrasting .. and ..., we have always used "asymmetric" vs "symmetric". I'd prefer to see usnot invent new phrase nobody has used, which leads to unnecessary confusion and learning burden. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH 0/2] Re: name for A..B ranges?
>> On Wed, Jun 22, 2016 at 08:25:59AM +0100, Philip Oakley wrote: >> >>> Is there a common name for the A..B range format (two dots) that would >>> complement the A...B (three dots) symmetric range format's name? $gmane/297908 Here is a short two patch series to hopefully enhance the revisions (and rev-parse) man page to help clarify the symmetric difference and two / three dots notations. The HTML versions look OK to me - tested on the Git-for-Windows SDK. Philip Oakley (2): doc: use 'symmetric difference' consistently doc: give headings for the two and three dot notations Documentation/gitk.txt | 2 +- Documentation/rev-list-options.txt | 4 ++-- Documentation/revisions.txt| 17 + 3 files changed, 16 insertions(+), 7 deletions(-) -- 2.8.4.windows.1.3.ge328a54 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: name for A..B ranges?
From: "Junio C Hamano" Jeff King writes: On Wed, Jun 22, 2016 at 08:25:59AM +0100, Philip Oakley wrote: Is there a common name for the A..B range format (two dots) that would complement the A...B (three dots) symmetric range format's name? I was looking at the --left-right distinctions and noticed that the trail back to the symmetric range description was rather thin (it's buried within gitrevisions:Specifying Ranges, and even then its called a symmetric difference. I would just call it a range, or possibly a set difference. But I don't think we have any established naming beyond that. Yup, I think "range" is the commonly used word in discussions here. When inventing A...B as a new thing in addition to A..B, we called the former "symmetric difference", and what is implied by that is the latter is "asymmetric difference"; we do not say that unless we are contrasting between the two, though. I asked because the man page does indicae that it (A..B) is a special sort of revison range and "there is a shorthand for it", but then didn't have a way of naming it. The symmetric difference is then brought in as a further similar notation. There are a number of Stackoverflow questions about the differences betwee 'two dots' and 'three dots' as well, so having a word/phrase for it could help. I was thinking that maybe "single-sided difference (two dots)" maybe one choice that is relatively neutral (or even a "two-dot range"...). -- Philip -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: name for A..B ranges?
Jeff King writes: > On Wed, Jun 22, 2016 at 08:25:59AM +0100, Philip Oakley wrote: > >> Is there a common name for the A..B range format (two dots) that would >> complement the A...B (three dots) symmetric range format's name? >> >> I was looking at the --left-right distinctions and noticed that the trail >> back to the symmetric range description was rather thin (it's buried within >> gitrevisions:Specifying Ranges, and even then its called a symmetric >> difference. > > I would just call it a range, or possibly a set difference. But I don't > think we have any established naming beyond that. Yup, I think "range" is the commonly used word in discussions here. When inventing A...B as a new thing in addition to A..B, we called the former "symmetric difference", and what is implied by that is the latter is "asymmetric difference"; we do not say that unless we are contrasting between the two, though. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: name for A..B ranges?
On Wed, Jun 22, 2016 at 08:25:59AM +0100, Philip Oakley wrote: > Is there a common name for the A..B range format (two dots) that would > complement the A...B (three dots) symmetric range format's name? > > I was looking at the --left-right distinctions and noticed that the trail > back to the symmetric range description was rather thin (it's buried within > gitrevisions:Specifying Ranges, and even then its called a symmetric > difference. I would just call it a range, or possibly a set difference. But I don't think we have any established naming beyond that. -Peff -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
name for A..B ranges?
Hi, Is there a common name for the A..B range format (two dots) that would complement the A...B (three dots) symmetric range format's name? I was looking at the --left-right distinctions and noticed that the trail back to the symmetric range description was rather thin (it's buried within gitrevisions:Specifying Ranges, and even then its called a symmetric difference. Philip -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
