rev-list: documentation and test for --left/right-only

diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
index cc562a057af3694d3518bc91b52ae322b6b1d9cc..cebba62239ad8861160e79255fdbdc4800be5e05 100644 (file)
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -13,7 +13,7 @@ include::pretty-options.txt[]
 
        Synonym for `--date=relative`.
 
---date={relative,local,default,iso,rfc,short,raw}::
+--date=(relative|local|default|iso|rfc|short|raw)::
 
        Only takes effect for dates shown in human-readable format, such
        as when using "--pretty". `log.date` config variable sets a default
@@ -45,13 +45,13 @@ endif::git-rev-list[]
 
 --parents::
 
-       Print the parents of the commit.  Also enables parent
-       rewriting, see 'History Simplification' below.
+       Print also the parents of the commit (in the form "commit parent...").
+       Also enables parent rewriting, see 'History Simplification' below.
 
 --children::
 
-       Print the children of the commit.  Also enables parent
-       rewriting, see 'History Simplification' below.
+       Print also the children of the commit (in the form "commit child...").
+       Also enables parent rewriting, see 'History Simplification' below.
 
 ifdef::git-rev-list[]
 --timestamp::
@@ -95,6 +95,8 @@ you would get an output like this:
        to be printed in between commits, in order for the graph history
        to be drawn properly.
 +
+This enables parent rewriting, see 'History Simplification' below.
++
 This implies the '--topo-order' option by default, but the
 '--date-order' option may also be specified.
 
@@ -146,6 +148,9 @@ options may be given. See linkgit:git-diff-files[1] for more options.
 -t::
 
        Show the tree objects in the diff output. This implies '-r'.
+
+-s::
+       Suppress diff output.
 endif::git-rev-list[]
 
 Commit Limiting
@@ -246,29 +251,29 @@ endif::git-rev-list[]
        Pretend as if all the refs in `refs/` are listed on the
        command line as '<commit>'.
 
---branches[=pattern]::
+--branches[=<pattern>]::
 
        Pretend as if all the refs in `refs/heads` are listed
-       on the command line as '<commit>'. If `pattern` is given, limit
+       on the command line as '<commit>'. If '<pattern>' is given, limit
        branches to ones matching given shell glob. If pattern lacks '?',
        '*', or '[', '/*' at the end is implied.
 
---tags[=pattern]::
+--tags[=<pattern>]::
 
        Pretend as if all the refs in `refs/tags` are listed
-       on the command line as '<commit>'. If `pattern` is given, limit
+       on the command line as '<commit>'. If '<pattern>' is given, limit
        tags to ones matching given shell glob. If pattern lacks '?', '*',
        or '[', '/*' at the end is implied.
 
---remotes[=pattern]::
+--remotes[=<pattern>]::
 
        Pretend as if all the refs in `refs/remotes` are listed
-       on the command line as '<commit>'. If `pattern`is given, limit
-       remote tracking branches to ones matching given shell glob.
+       on the command line as '<commit>'. If '<pattern>' is given, limit
+       remote-tracking branches to ones matching given shell glob.
        If pattern lacks '?', '*', or '[', '/*' at the end is implied.
 
---glob=glob-pattern::
-       Pretend as if all the refs matching shell glob `glob-pattern`
+--glob=<glob-pattern>::
+       Pretend as if all the refs matching shell glob '<glob-pattern>'
        are listed on the command line as '<commit>'. Leading 'refs/',
        is automatically prepended if missing. If pattern lacks '?', '*',
        or '[', '/*' at the end is implied.
@@ -314,6 +319,19 @@ from the other branch (for example, "3rd on b" may be cherry-picked
 from branch A).  With this option, such pairs of commits are
 excluded from the output.
 
+--left-only::
+--right-only::
+
+       List only commits on the respective side of a symmetric range,
+       i.e. only those which would be marked `<` resp. `>` by
+       `--left-right`.
++
+For example, `--cherry-pick --right-only A...B` omits those
+commits from `B` which are in `A` or are patch-equivalent to a commit in
+`A`. In other words, this lists the `{plus}` commits from `git cherry A B`.
+More precisely, `--cherry-pick --right-only --no-merges` gives the exact
+list.
+
 -g::
 --walk-reflogs::
 
@@ -321,7 +339,7 @@ excluded from the output.
        reflog entries from the most recent one to older ones.
        When this option is used you cannot specify commits to
        exclude (that is, '{caret}commit', 'commit1..commit2',
-       nor 'commit1...commit2' notations cannot be used).
+       nor 'commit1\...commit2' notations cannot be used).
 +
 With '\--pretty' format other than oneline (for obvious reasons),
 this causes the output to have two extra lines of information