Docs: send-email: --chain_reply_to -> --[no-]chain-reply-to
[gitweb.git] / Documentation / rev-list-options.txt
index ce6a1017a34aed25efc192e889a9f04adb5aa2f3..0ce916a1887b0846bfc5a6e2233242601e0dde79 100644 (file)
@@ -13,10 +13,11 @@ include::pretty-options.txt[]
 
        Synonym for `--date=relative`.
 
---date={relative,local,default,iso,rfc}::
+--date={relative,local,default,iso,rfc,short}::
 
        Only takes effect for dates shown in human-readable format, such
-       as when using "--pretty".
+       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".
@@ -33,17 +34,27 @@ format, often found in E-mail messages.
 `--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 the parents of the commit.
+       Print the parents of the commit.  Also enables parent
+       rewriting, see 'History Simplification' below.
+
+--children::
 
+       Print the children of the commit.  Also enables parent
+       rewriting, see 'History Simplification' below.
+
+ifdef::git-rev-list[]
 --timestamp::
        Print the raw commit timestamp.
+endif::git-rev-list[]
 
 --left-right::
 
@@ -62,7 +73,7 @@ For example, if you have this topology:
          o---x---a---a  branch A
 -----------------------------------------------------------------------
 +
-you would get an output line this:
+you would get an output like this:
 +
 -----------------------------------------------------------------------
        $ git rev-list --left-right --boundary --pretty=oneline A...B
@@ -85,6 +96,7 @@ you would get an output line this:
 This implies the '--topo-order' option by default, but the
 '--date-order' option may also be specified.
 
+ifndef::git-rev-list[]
 Diff Formatting
 ~~~~~~~~~~~~~~~
 
@@ -103,9 +115,9 @@ options may be given. See linkgit:git-diff-files[1] for more options.
 --cc::
 
        This flag implies the '-c' options and further compresses the
-       patch output by omitting hunks that show differences from only
-       one parent, or show the same change from all but one parent for
-       an Octopus merge.
+       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.
 
 -r::
 
@@ -114,6 +126,7 @@ 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'.
+endif::git-rev-list[]
 
 Commit Limiting
 ~~~~~~~~~~~~~~~
@@ -124,7 +137,8 @@ limiting may be applied.
 
 --
 
--n 'number', --max-count='number'::
+-n 'number'::
+--max-count='number'::
 
        Limit the number of commits output.
 
@@ -132,21 +146,25 @@ limiting may be applied.
 
        Skip 'number' commits before starting to show the commit output.
 
---since='date', --after='date'::
+--since='date'::
+--after='date'::
 
        Show commits more recent than a specific date.
 
---until='date', --before='date'::
+--until='date'::
+--before='date'::
 
        Show commits older than a specific date.
 
 ifdef::git-rev-list[]
---max-age='timestamp', --min-age='timestamp'::
+--max-age='timestamp'::
+--min-age='timestamp'::
 
        Limit the commits output to specified time range.
 endif::git-rev-list[]
 
---author='pattern', --committer='pattern'::
+--author='pattern'::
+--committer='pattern'::
 
        Limit the commits output to ones with author/committer
        header lines that match the specified pattern (regular expression).
@@ -156,16 +174,19 @@ endif::git-rev-list[]
        Limit the commits output to ones with log message that
        matches the specified pattern (regular expression).
 
--i, --regexp-ignore-case::
+-i::
+--regexp-ignore-case::
 
        Match the regexp limiting patterns without regard to letters case.
 
--E, --extended-regexp::
+-E::
+--extended-regexp::
 
        Consider the limiting patterns to be extended regular expressions
        instead of the default basic regular expressions.
 
--F, --fixed-strings::
+-F::
+--fixed-strings::
 
        Consider the limiting patterns to be fixed strings (don't interpret
        pattern as a regular expression).
@@ -174,14 +195,6 @@ endif::git-rev-list[]
 
        Stop when a given path disappears from the tree.
 
---full-history::
-
-       Show also parts of history irrelevant to current state of a given
-       path. This turns off history simplification, which removed merges
-       which didn't change anything at all at some child. It will still actually
-       simplify away merges that didn't change anything at all into either
-       child.
-
 --no-merges::
 
        Do not print commits with more than one parent.
@@ -205,6 +218,7 @@ endif::git-rev-list[]
        Pretend as if all the refs in `$GIT_DIR/refs/` are listed on the
        command line as '<commit>'.
 
+ifdef::git-rev-list[]
 --stdin::
 
        In addition to the '<commit>' listed on the command
@@ -217,6 +231,7 @@ endif::git-rev-list[]
        test the exit status to see if a range of objects is fully
        connected (or not).  It is faster than redirecting stdout
        to /dev/null as the output does not have to be formatted.
+endif::git-rev-list[]
 
 --cherry-pick::
 
@@ -232,7 +247,8 @@ 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.
 
--g, --walk-reflogs::
+-g::
+--walk-reflogs::
 
        Instead of walking the commit ancestry chain, walk
        reflog entries from the most recent one to older ones.
@@ -244,11 +260,10 @@ With '\--pretty' format other than oneline (for obvious reasons),
 this causes the output to have two extra lines of information
 taken from the reflog.  By default, 'commit@\{Nth}' notation is
 used in the output.  When the starting commit is specified as
-'commit@{now}', output also uses 'commit@\{timestamp}' notation
+'commit@\{now}', output also uses 'commit@\{timestamp}' notation
 instead.  Under '\--pretty=oneline', the commit message is
 prefixed with this information on the same line.
-
-Cannot be combined with '\--reverse'.
+This option cannot be combined with '\--reverse'.
 See also linkgit:git-reflog[1].
 
 --merge::
@@ -261,17 +276,186 @@ See also linkgit:git-reflog[1].
        Output uninteresting commits at the boundary, which are usually
        not shown.
 
---dense, --sparse::
+--
+
+History Simplification
+~~~~~~~~~~~~~~~~~~~~~~
+
+When optional paths are given, 'git-rev-list' simplifies commits with
+various strategies, according to the options you have selected.
+
+Suppose you specified `foo` as the <paths>.  We shall call commits
+that modify `foo` !TREESAME, and the rest TREESAME.  (In a diff
+filtered for `foo`, they look different and equal, respectively.)
+
+In the following, we will always refer to the same example history to
+illustrate the differences between simplification settings.  We assume
+that you are filtering for a file `foo` in this commit graph:
+-----------------------------------------------------------------------
+         .-A---M---N---O---P
+        /     /   /   /   /
+       I     B   C   D   E
+        \   /   /   /   /
+         `-------------'
+-----------------------------------------------------------------------
+The horizontal line of history A--P is taken to be the first parent of
+each merge.  The commits are:
 
-When optional paths are given, the default behaviour ('--dense') is to
-only output commits that changes at least one of them, and also ignore
-merges that do not touch the given paths.
+* `I` is the initial commit, in which `foo` exists with contents
+  "asdf", and a file `quux` exists with contents "quux".  Initial
+  commits are compared to an empty tree, so `I` is !TREESAME.
 
-Use the '--sparse' flag to makes the command output all eligible commits
-(still subject to count and age limitation), but apply merge
-simplification nevertheless.
+* In `A`, `foo` contains just "foo".
+
+* `B` contains the same change as `A`.  Its merge `M` is trivial and
+  hence TREESAME to all parents.
+
+* `C` does not change `foo`, but its merge `N` changes it to "foobar",
+  so it is not TREESAME to any parent.
+
+* `D` sets `foo` to "baz".  Its merge `O` combines the strings from
+  `N` and `D` to "foobarbaz"; i.e., it is not TREESAME to any parent.
+
+* `E` changes `quux` to "xyzzy", and its merge `P` combines the
+  strings to "quux xyzzy".  Despite appearing interesting, `P` is
+  TREESAME to all parents.
+
+'rev-list' walks backwards through history, including or excluding
+commits based on whether '\--full-history' and/or parent rewriting
+(via '\--parents' or '\--children') are used.  The following settings
+are available.
+
+Default mode::
+
+       Commits are included if they are not TREESAME to any parent
+       (though this can be changed, see '\--sparse' below).  If the
+       commit was a merge, and it was TREESAME to one parent, follow
+       only that parent.  (Even if there are several TREESAME
+       parents, follow only one of them.)  Otherwise, follow all
+       parents.
++
+This results in:
++
+-----------------------------------------------------------------------
+         .-A---N---O
+        /         /
+       I---------D
+-----------------------------------------------------------------------
++
+Note how the rule to only follow the TREESAME parent, if one is
+available, removed `B` from consideration entirely.  `C` was
+considered via `N`, but is TREESAME.  Root commits are compared to an
+empty tree, so `I` is !TREESAME.
++
+Parent/child relations are only visible with --parents, but that does
+not affect the commits selected in default mode, so we have shown the
+parent lines.
+
+--full-history without parent rewriting::
+
+       This mode differs from the default in one point: always follow
+       all parents of a merge, even if it is TREESAME to one of them.
+       Even if more than one side of the merge has commits that are
+       included, this does not imply that the merge itself is!  In
+       the example, we get
++
+-----------------------------------------------------------------------
+       I  A  B  N  D  O
+-----------------------------------------------------------------------
++
+`P` and `M` were excluded because they are TREESAME to a parent.  `E`,
+`C` and `B` were all walked, but only `B` was !TREESAME, so the others
+do not appear.
++
+Note that without parent rewriting, it is not really possible to talk
+about the parent/child relationships between the commits, so we show
+them disconnected.
+
+--full-history with parent rewriting::
+
+       Ordinary commits are only included if they are !TREESAME
+       (though this can be changed, see '\--sparse' below).
++
+Merges are always included.  However, their parent list is rewritten:
+Along each parent, prune away commits that are not included
+themselves.  This results in
++
+-----------------------------------------------------------------------
+         .-A---M---N---O---P
+        /     /   /   /   /
+       I     B   /   D   /
+        \   /   /   /   /
+         `-------------'
+-----------------------------------------------------------------------
++
+Compare to '\--full-history' without rewriting above.  Note that `E`
+was pruned away because it is TREESAME, but the parent list of P was
+rewritten to contain `E`'s parent `I`.  The same happened for `C` and
+`N`.  Note also that `P` was included despite being TREESAME.
+
+In addition to the above settings, you can change whether TREESAME
+affects inclusion:
+
+--dense::
+
+       Commits that are walked are included if they are not TREESAME
+       to any parent.
+
+--sparse::
+
+       All commits that are walked are included.
++
+Note that without '\--full-history', this still simplifies merges: if
+one of the parents is TREESAME, we follow only that one, so the other
+sides of the merge are never walked.
+
+Finally, there is a fourth simplification mode available:
+
+--simplify-merges::
+
+       First, build a history graph in the same way that
+       '\--full-history' with parent rewriting does (see above).
++
+Then simplify each commit `C` to its replacement `C'` in the final
+history according to the following rules:
++
+--
+* Set `C'` to `C`.
++
+* Replace each parent `P` of `C'` with its simplification `P'`.  In
+  the process, drop parents that are ancestors of other parents, and
+  remove duplicates.
++
+* If after this parent rewriting, `C'` is a root or merge commit (has
+  zero or >1 parents), a boundary commit, or !TREESAME, it remains.
+  Otherwise, it is replaced with its only parent.
+--
++
+The effect of this is best shown by way of comparing to
+'\--full-history' with parent rewriting.  The example turns into:
++
+-----------------------------------------------------------------------
+         .-A---M---N---O
+        /     /       /
+       I     B       D
+        \   /       /
+         `---------'
+-----------------------------------------------------------------------
++
+Note the major differences in `N` and `P` over '\--full-history':
++
+--
+* `N`'s parent list had `I` removed, because it is an ancestor of the
+  other parent `M`.  Still, `N` remained because it is !TREESAME.
++
+* `P`'s parent list similarly had `I` removed.  `P` was then
+  removed completely, because it had one parent and is TREESAME.
+--
 
 ifdef::git-rev-list[]
+Bisection Helpers
+~~~~~~~~~~~~~~~~~
+
 --bisect::
 
 Limit output to the one commit object which is roughly halfway between
@@ -321,7 +505,6 @@ after all the sorted commit objects, there will be the same text as if
 `--bisect-vars` had been used alone.
 endif::git-rev-list[]
 
---
 
 Commit Ordering
 ~~~~~~~~~~~~~~~