index-pack: support multithreaded delta resolving
[gitweb.git] / Documentation / rev-list-options.txt
index 42ca059908b6af5726d958d92912705c96235d29..39e62072691d408519ff377cb6e91e8d95175ec4 100644 (file)
-Commit Formatting
-~~~~~~~~~~~~~~~~~
-
-ifdef::git-rev-list[]
-Using these options, linkgit:git-rev-list[1] will act similar to the
-more specialized family of commit log tools: linkgit:git-log[1],
-linkgit:git-show[1], and linkgit:git-whatchanged[1]
-endif::git-rev-list[]
-
-include::pretty-options.txt[]
-
---relative-date::
-
-       Synonym for `--date=relative`.
-
---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
-       value for log command's --date option.
-+
-`--date=relative` shows dates relative to the current time,
-e.g. "2 hours ago".
-+
-`--date=local` shows timestamps in user's local timezone.
-+
-`--date=iso` (or `--date=iso8601`) shows timestamps in ISO 8601 format.
-+
-`--date=rfc` (or `--date=rfc2822`) shows timestamps in RFC 2822
-format, often found in E-mail messages.
-+
-`--date=short` shows only date but not time, in `YYYY-MM-DD` format.
-+
-`--date=raw` shows the date in the internal raw git format `%s %z` format.
-+
-`--date=default` shows timestamps in the original timezone
-(either committer's or author's).
-
-ifdef::git-rev-list[]
---header::
-
-       Print the contents of the commit in raw-format; each record is
-       separated with a NUL character.
-endif::git-rev-list[]
-
---parents::
-
-       Print also the parents of the commit (in the form "commit parent...").
-       Also enables parent rewriting, see 'History Simplification' below.
-
---children::
-
-       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::
-       Print the raw commit timestamp.
-endif::git-rev-list[]
-
---left-right::
-
-       Mark which side of a symmetric diff a commit is reachable from.
-       Commits from the left side are prefixed with `<` and those from
-       the right with `>`.  If combined with `--boundary`, those
-       commits are prefixed with `-`.
-+
-For example, if you have this topology:
-+
------------------------------------------------------------------------
-             y---b---b  branch B
-            / \ /
-           /   .
-          /   / \
-         o---x---a---a  branch A
------------------------------------------------------------------------
-+
-you would get an output like this:
-+
------------------------------------------------------------------------
-       $ git rev-list --left-right --boundary --pretty=oneline A...B
-
-       >bbbbbbb... 3rd on b
-       >bbbbbbb... 2nd on b
-       <aaaaaaa... 3rd on a
-       <aaaaaaa... 2nd on a
-       -yyyyyyy... 1st on b
-       -xxxxxxx... 1st on a
------------------------------------------------------------------------
-
---graph::
-
-       Draw a text-based graphical representation of the commit history
-       on the left hand side of the output.  This may cause extra lines
-       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.
-
-ifdef::git-rev-list[]
---count::
-       Print a number stating how many commits would have been
-       listed, and suppress all other output.  When used together
-       with '--left-right', instead print the counts for left and
-       right commits, separated by a tab.
-endif::git-rev-list[]
-
-
-ifndef::git-rev-list[]
-Diff Formatting
-~~~~~~~~~~~~~~~
-
-Below are listed options that control the formatting of diff output.
-Some of them are specific to linkgit:git-rev-list[1], however other diff
-options may be given. See linkgit:git-diff-files[1] for more options.
-
--c::
-
-       With this option, diff output for a merge commit
-       shows the differences from each of the parents to the merge result
-       simultaneously instead of showing pairwise diff between a parent
-       and the result one at a time. Furthermore, it lists only files
-       which were modified from all parents.
-
---cc::
-
-       This flag implies the '-c' options 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.
-
--m::
-
-       This flag makes the merge commits show the full diff like
-       regular commits; for each merge parent, a separate log entry
-       and diff is generated. An exception is that only diff against
-       the first parent is shown when '--first-parent' option is given;
-       in that case, the output represents the changes the merge
-       brought _into_ the then-current branch.
-
--r::
-
-       Show recursive diffs.
-
--t::
-
-       Show the tree objects in the diff output. This implies '-r'.
-
--s::
-       Suppress diff output.
-endif::git-rev-list[]
-
 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.
+limiting may be applied. Note that they are applied before commit
+ordering and formatting options, such as '--reverse'.
 
 --
 
 -n 'number'::
 --max-count=<number>::
 
-       Limit the number of commits output.
+       Limit the number of commits to output.
 
 --skip=<number>::
 
@@ -226,11 +72,26 @@ endif::git-rev-list[]
 
 --merges::
 
-       Print only merge commits.
+       Print only merge commits. This is exactly the same as `--min-parents=2`.
 
 --no-merges::
 
-       Do not print commits with more than one parent.
+       Do not print commits with more than one parent. This is
+       exactly the same as `--max-parents=1`.
+
+--min-parents=<number>::
+--max-parents=<number>::
+--no-min-parents::
+--no-max-parents::
+
+       Show only commits which have at least (or at most) that many
+       commits. In particular, `--max-parents=1` is the same as `--no-merges`,
+       `--min-parents=2` is the same as `--merges`.  `--max-parents=0`
+       gives all root commits and `--min-parents=3` all octopus merges.
++
+`--no-min-parents` and `--no-max-parents` reset these limits (to no limit)
+again.  Equivalent forms are `--min-parents=0` (any commit has 0 or more
+parents) and `--max-parents=-1` (negative numbers denote no upper limit).
 
 --first-parent::
        Follow only the first parent commit upon seeing a merge
@@ -269,7 +130,7 @@ endif::git-rev-list[]
 
        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.
+       remote-tracking branches to ones matching given shell glob.
        If pattern lacks '?', '*', or '[', '/*' at the end is implied.
 
 --glob=<glob-pattern>::
@@ -278,6 +139,10 @@ endif::git-rev-list[]
        is automatically prepended if missing. If pattern lacks '?', '*',
        or '[', '/*' at the end is implied.
 
+--ignore-missing::
+
+       Upon seeing an invalid object name in the input, pretend as if
+       the bad input was not given.
 
 ifndef::git-rev-list[]
 --bisect::
@@ -305,6 +170,11 @@ ifdef::git-rev-list[]
        to /dev/null as the output does not have to be formatted.
 endif::git-rev-list[]
 
+--cherry-mark::
+
+       Like `--cherry-pick` (see below) but mark equivalent commits
+       with `=` rather than omitting them, and inequivalent ones with `+`.
+
 --cherry-pick::
 
        Omit any commit that introduces the same change as
@@ -313,12 +183,33 @@ endif::git-rev-list[]
 +
 For example, if you have two branches, `A` and `B`, a usual way
 to list all commits on only one side of them is with
-`--left-right`, like the example above in the description of
-that option.  It however shows the commits that were cherry-picked
+`--left-right` (see the example below in the description of
+the `--left-right` option).  It however shows the commits that were cherry-picked
 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.
+
+--cherry::
+
+       A synonym for `--right-only --cherry-mark --no-merges`; useful to
+       limit the output to the commits on our side and mark those that
+       have been applied to the other side of a forked history with
+       `git log --cherry upstream...mybranch`, similar to
+       `git cherry upstream mybranch`.
+
 -g::
 --walk-reflogs::
 
@@ -381,7 +272,7 @@ Default mode::
 
 --full-history::
 
-       As the default mode but does not prune some history.
+       Same as the default mode, but does not prune some history.
 
 --dense::
 
@@ -422,7 +313,7 @@ that you are filtering for a file `foo` in this commit graph:
         \   /   /   /   /
          `-------------'
 -----------------------------------------------------------------------
-The horizontal line of history A--P is taken to be the first parent of
+The horizontal line of history A---P is taken to be the first parent of
 each merge.  The commits are:
 
 * `I` is the initial commit, in which `foo` exists with contents
@@ -735,3 +626,161 @@ These options are mostly targeted for packing of git repositories.
 --do-walk::
 
        Overrides a previous --no-walk.
+
+Commit Formatting
+~~~~~~~~~~~~~~~~~
+
+ifdef::git-rev-list[]
+Using these options, linkgit:git-rev-list[1] will act similar to the
+more specialized family of commit log tools: linkgit:git-log[1],
+linkgit:git-show[1], and linkgit:git-whatchanged[1]
+endif::git-rev-list[]
+
+include::pretty-options.txt[]
+
+--relative-date::
+
+       Synonym for `--date=relative`.
+
+--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
+       value for log command's --date option.
++
+`--date=relative` shows dates relative to the current time,
+e.g. "2 hours ago".
++
+`--date=local` shows timestamps in user's local timezone.
++
+`--date=iso` (or `--date=iso8601`) shows timestamps in ISO 8601 format.
++
+`--date=rfc` (or `--date=rfc2822`) shows timestamps in RFC 2822
+format, often found in E-mail messages.
++
+`--date=short` shows only date but not time, in `YYYY-MM-DD` format.
++
+`--date=raw` shows the date in the internal raw git format `%s %z` format.
++
+`--date=default` shows timestamps in the original timezone
+(either committer's or author's).
+
+ifdef::git-rev-list[]
+--header::
+
+       Print the contents of the commit in raw-format; each record is
+       separated with a NUL character.
+endif::git-rev-list[]
+
+--parents::
+
+       Print also the parents of the commit (in the form "commit parent...").
+       Also enables parent rewriting, see 'History Simplification' below.
+
+--children::
+
+       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::
+       Print the raw commit timestamp.
+endif::git-rev-list[]
+
+--left-right::
+
+       Mark which side of a symmetric diff a commit is reachable from.
+       Commits from the left side are prefixed with `<` and those from
+       the right with `>`.  If combined with `--boundary`, those
+       commits are prefixed with `-`.
++
+For example, if you have this topology:
++
+-----------------------------------------------------------------------
+            y---b---b  branch B
+           / \ /
+          /   .
+         /   / \
+        o---x---a---a  branch A
+-----------------------------------------------------------------------
++
+you would get an output like this:
++
+-----------------------------------------------------------------------
+       $ git rev-list --left-right --boundary --pretty=oneline A...B
+
+       >bbbbbbb... 3rd on b
+       >bbbbbbb... 2nd on b
+       <aaaaaaa... 3rd on a
+       <aaaaaaa... 2nd on a
+       -yyyyyyy... 1st on b
+       -xxxxxxx... 1st on a
+-----------------------------------------------------------------------
+
+--graph::
+
+       Draw a text-based graphical representation of the commit history
+       on the left hand side of the output.  This may cause extra lines
+       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.
+
+ifdef::git-rev-list[]
+--count::
+       Print a number stating how many commits would have been
+       listed, and suppress all other output.  When used together
+       with '--left-right', instead print the counts for left and
+       right commits, separated by a tab. When used together with
+       '--cherry-mark', omit patch equivalent commits from these
+       counts and print the count for equivalent commits separated
+       by a tab.
+endif::git-rev-list[]
+
+
+ifndef::git-rev-list[]
+Diff Formatting
+~~~~~~~~~~~~~~~
+
+Below are listed options that control the formatting of diff output.
+Some of them are specific to linkgit:git-rev-list[1], however other diff
+options may be given. See linkgit:git-diff-files[1] for more options.
+
+-c::
+
+       With this option, diff output for a merge commit
+       shows the differences from each of the parents to the merge result
+       simultaneously instead of showing pairwise diff between a parent
+       and the result one at a time. Furthermore, it lists only files
+       which were modified from all parents.
+
+--cc::
+
+       This flag implies the '-c' options 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.
+
+-m::
+
+       This flag makes the merge commits show the full diff like
+       regular commits; for each merge parent, a separate log entry
+       and diff is generated. An exception is that only diff against
+       the first parent is shown when '--first-parent' option is given;
+       in that case, the output represents the changes the merge
+       brought _into_ the then-current branch.
+
+-r::
+
+       Show recursive diffs.
+
+-t::
+
+       Show the tree objects in the diff output. This implies '-r'.
+
+-s::
+       Suppress diff output.
+endif::git-rev-list[]