Re: [PATCH v4 4/8] doc: give headings for the two and three dot notations

2016-07-22 Thread Junio C Hamano 
Philip Oakley  writes:

> +Special '{caret}' Shorthand Notations
> +~~
> +Two other shorthands exist, particularly useful for merge commits, is
> +for naming a set that is formed by a commit and its parent commits.

As these are not all that "special", how about retitling this
section as:

Other Shorthand Notations
~


> -To summarize:
> +The 'r1{caret}@' notation means all parents of 'r1'.
> +
> +'r1{caret}!' includes commit 'r1' but excludes all of its parents.
> +
> +Revision Range Summary
> +--
>  
>  ''::
>   Include commits that are reachable from (i.e. ancestors of)
--
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 v4 4/8] doc: give headings for the two and three dot notations

2016-07-21 Thread Marc Branchaud 

On 2016-07-21 03:54 PM, Philip Oakley wrote:

From: "Marc Branchaud" 

On 2016-07-20 05:10 PM, Philip Oakley wrote:

While there, also break out the other shorthand notations and
add a title for the revision range summary (which also appears
in git-rev-parse, so keep it mixed case).

Signed-off-by: Philip Oakley 
---
  Documentation/revisions.txt | 58
-
  1 file changed, 36 insertions(+), 22 deletions(-)

diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index 6e9cd41..5b37283 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt
@@ -242,35 +242,49 @@ 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.

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


s/called/called the/


The wording is the original ;-) Can change.




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

-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.
+Special '{caret}' Shorthand Notations
+~~


Sorry, but this header also does not render properly in the man page.
Maybe just "Special {caret} Shorthand Notations"?  (But read on!)


rendered fine on the MYS2 man invocation - I had had to add the 
prefix to the quoted title to make it work.

What went wrong for you? (I'll read on)


Only the word "Special" is emphasized (in bold).  The rest of the header 
is plain.


I'm using asciidoc 8.6.9, so I'm likely suffering from the bug Peff 
identified.





+Two other shorthands exist, particularly useful for merge commits, is
+for naming a set that is formed by a commit and its parent commits.

-To summarize:
+The 'r1{caret}@' notation means all parents of 'r1'.
+
+'r1{caret}!' includes commit 'r1' but excludes all of its parents.


My immediate thought upon reading this is "Why not just use 'r1'?"  I
think the answer is "This truncates the range."  So, for example, "git
log r1" shows you r1 and its ancestors, while "git log r1^!" only
shows you r1.  I think you should add this example, or something similar.



I'd also asked that question in one of my replies earlier $gmane/299849.
I was then able to determine that it was a width wide 'range' covering
multi-parent situations.


Obviously, I see it more an anti-range.  You're never going to get more 
than a single commit with this notation.



Identifying an example could be good if it was succinct and explanatory.


What do you think of my

Re: [PATCH v4 4/8] doc: give headings for the two and three dot notations

2016-07-21 Thread Philip Oakley 

From: "Marc Branchaud" 

On 2016-07-20 05:10 PM, Philip Oakley wrote:

While there, also break out the other shorthand notations and
add a title for the revision range summary (which also appears
in git-rev-parse, so keep it mixed case).

Signed-off-by: Philip Oakley 
---
  Documentation/revisions.txt | 58 
-

  1 file changed, 36 insertions(+), 22 deletions(-)

diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index 6e9cd41..5b37283 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt
@@ -242,35 +242,49 @@ 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.

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

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


s/called/called the/


The wording is the original ;-) Can change.




+ 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

  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.

-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.
+Special '{caret}' Shorthand Notations
+~~


Sorry, but this header also does not render properly in the man page. 
Maybe just "Special {caret} Shorthand Notations"?  (But read on!)


rendered fine on the MYS2 man invocation - I had had to add the  prefix 
to the quoted title to make it work.


What went wrong for you? (I'll read on)





+Two other shorthands exist, particularly useful for merge commits, is
+for naming a set that is formed by a commit and its parent commits.

-To summarize:
+The 'r1{caret}@' notation means all parents of 'r1'.
+
+'r1{caret}!' includes commit 'r1' but excludes all of its parents.


My immediate thought upon reading this is "Why not just use 'r1'?"  I 
think the answer is "This truncates the range."  So, for example, "git log 
r1" shows you r1 and its ancestors, while "git log r1^!" only shows you 
r1.  I think you should add this example, or something similar.




I'd also asked that question in one of my replies earlier $gmane/299849. I 
was then able to determine that it was a width wide 'range' covering 
multi-parent situations.


Identifying an example could be good if it was succinct and explanatory.

$ git rev-parse 6c71a849^!
But, really, this means that the notation is another "Commit Exclusion" 
and properly belongs in that section.


I think it's bigger than that.


That makes this "Special Notations" section rather thin.  I suggest moving 
a slightly expanded ^@ description to a small subsection just before 
Commit

Re: [PATCH v4 4/8] doc: give headings for the two and three dot notations

2016-07-21 Thread Marc Branchaud 

On 2016-07-20 05:10 PM, Philip Oakley wrote:

While there, also break out the other shorthand notations and
add a title for the revision range summary (which also appears
in git-rev-parse, so keep it mixed case).

Signed-off-by: Philip Oakley 
---
  Documentation/revisions.txt | 58 -
  1 file changed, 36 insertions(+), 22 deletions(-)

diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index 6e9cd41..5b37283 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt
@@ -242,35 +242,49 @@ 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.

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


s/called/called the/


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

-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.
+Special '{caret}' Shorthand Notations
+~~


Sorry, but this header also does not render properly in the man page. 
Maybe just "Special {caret} Shorthand Notations"?  (But read on!)



+Two other shorthands exist, particularly useful for merge commits, is
+for naming a set that is formed by a commit and its parent commits.

-To summarize:
+The 'r1{caret}@' notation means all parents of 'r1'.
+
+'r1{caret}!' includes commit 'r1' but excludes all of its parents.


My immediate thought upon reading this is "Why not just use 'r1'?"  I 
think the answer is "This truncates the range."  So, for example, "git 
log r1" shows you r1 and its ancestors, while "git log r1^!" only shows 
you r1.  I think you should add this example, or something similar.


But, really, this means that the notation is another "Commit Exclusion" 
and properly belongs in that section.


That makes this "Special Notations" section rather thin.  I suggest 
moving a slightly expanded ^@ description to a small subsection 
just before Commit Exclusions, and deleting the Special Notations 
section altogether.  So add something like this:


Commit Parents
~~

'{caret}@' Notation::
 The 'r1{caret}@' notation means all parents of 'r1',
 excluding 'r1' itself.

This smoothly re-introduces the notion of parents for readers who 
skipped to this section, and helps them make sense of the ^! notation.


Plus there's no longer anything "special" about any of the syntax.


+
+Revision Range Summary
+--


Sorry, but the man page renders this in all

[PATCH v4 4/8] doc: give headings for the two and three dot notations

2016-07-20 Thread Philip Oakley 
While there, also break out the other shorthand notations and
add a title for the revision range summary (which also appears
in git-rev-parse, so keep it mixed case).

Signed-off-by: Philip Oakley 
---
 Documentation/revisions.txt | 58 -
 1 file changed, 36 insertions(+), 22 deletions(-)

diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index 6e9cd41..5b37283 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt
@@ -242,35 +242,49 @@ 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.
 
-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'.
-
-This 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'.
-
-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.
+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'.
+
+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
 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.
 
-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.
+Special '{caret}' Shorthand Notations
+~~
+Two other shorthands exist, particularly useful for merge commits, is
+for naming a set that is formed by a commit and its parent commits.
 
-To summarize:
+The 'r1{caret}@' notation means all parents of 'r1'.
+
+'r1{caret}!' includes commit 'r1' but excludes all of its parents.
+
+Revision Range Summary
+--
 
 ''::
Include commits that are reachable from (i.e. ancestors of)
-- 
2.9.0.windows.1

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