Merge branch 'jc/maint-log-grep-all-match-1' into maint

[git.git] / Documentation / rev-list-options.txt

diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
index 84e34b1abaf23ef87fcccd21b0500fd21c5a1912..1fc2a18404bd34a2e1ac9f5fe21d64c1827f13a6 100644 (file)
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -3,12 +3,20 @@ Commit Limiting
 
 Besides specifying a range of commits that should be listed using the
 special notations explained in the description, additional commit
-limiting may be applied. Note that they are applied before commit
-ordering and formatting options, such as '--reverse'.
+limiting may be applied.
+
+Using more options generally further limits the output (e.g.
+`--since=<date1>` limits to commits newer than `<date1>`, and using it
+with `--grep=<pattern>` further limits to commits whose log message
+has a line that matches `<pattern>`), unless otherwise noted.
+
+Note that these are applied before commit
+ordering and formatting options, such as `--reverse`.
 
 --
 
--n 'number'::
+-<number>::
+-n <number>::
 --max-count=<number>::
 
        Limit the number of commits to output.
@@ -38,16 +46,22 @@ endif::git-rev-list[]
 --committer=<pattern>::
 
        Limit the commits output to ones with author/committer
-       header lines that match the specified pattern (regular expression).
+       header lines that match the specified pattern (regular
+       expression).  With more than one `--author=<pattern>`,
+       commits whose author matches any of the given patterns are
+       chosen (similarly for multiple `--committer=<pattern>`).
 
 --grep=<pattern>::
 
        Limit the commits output to ones with log message that
-       matches the specified pattern (regular expression).
+       matches the specified pattern (regular expression).  With
+       more than one `--grep=<pattern>`, commits whose message
+       matches any of the given patterns are chosen (but see
+       `--all-match`).
 
 --all-match::
        Limit the commits output to ones that match all given --grep,
-       --author and --committer instead of ones that match at least one.
+       instead of ones that match at least one.
 
 -i::
 --regexp-ignore-case::
@@ -578,16 +592,33 @@ Commit Ordering
 
 By default, the commits are shown in reverse chronological order.
 
---topo-order::
+--date-order::
+       Show no parents before all of its children are shown, but
+       otherwise show commits in the commit timestamp order.
 
-       This option makes them appear in topological order (i.e.
-       descendant commits are shown before their parents).
+--topo-order::
+       Show no parents before all of its children are shown, and
+       avoid showing commits on multiple lines of history
+       intermixed.
++
+For example, in a commit history like this:
++
+----------------------------------------------------------------
 
---date-order::
+    ---1----2----4----7
+       \              \
+        3----5----6----8---
 
-       This option is similar to '--topo-order' in the sense that no
-       parent comes before all of its children, but otherwise things
-       are still ordered in the commit timestamp order.
+----------------------------------------------------------------
++
+where the numbers denote the order of commit timestamps, `git
+rev-list` and friends with `--date-order` show the commits in the
+timestamp order: 8 7 6 5 4 3 2 1.
++
+With `--topo-order`, they would show 8 6 5 3 7 4 2 1 (or 8 7 4 2 6 5
+3 1); some older commits are shown before newer ones in order to
+avoid showing the commits from two parallel development track mixed
+together.
 
 --reverse::
 
@@ -619,10 +650,14 @@ These options are mostly targeted for packing of git repositories.
        Only useful with '--objects'; print the object IDs that are not
        in packs.
 
---no-walk::
+--no-walk[=(sorted|unsorted)]::
 
-       Only show the given revs, but do not traverse their ancestors.
-       This has no effect if a range is specified.
+       Only show the given commits, but do not traverse their ancestors.
+       This has no effect if a range is specified. If the argument
+       "unsorted" is given, the commits are show in the order they were
+       given on the command line. Otherwise (if "sorted" or no argument
+       was given), the commits are show in reverse chronological order
+       by commit time.
 
 --do-walk::
 
@@ -760,7 +795,7 @@ options may be given. See linkgit:git-diff-files[1] for more options.
 
 --cc::
 
-       This flag implies the '-c' options and further compresses the
+       This flag implies the '-c' option and further compresses the
        patch output by omitting uninteresting hunks whose contents in
        the parents have only two variants and the merge result picks
        one of them without modification.