* git-diff --check now checks leftover merge conflict markers.
* "git-diff -p" learned to grab a better hunk header lines in
- Pascal/Delphi and Ruby source files, and also pays attention to
+ BibTex, Pascal/Delphi, and Ruby files and also pays attention to
chapter and part boundary in TeX documents.
* When remote side used to have branch 'foo' and git-fetch finds that now
---
exec >/var/tmp/1
-O=v1.6.0-rc2-21-g0bb3a0b
+O=v1.6.0-rc3
echo O=$(git describe refs/heads/master)
git shortlog --no-merges $O..refs/heads/master ^refs/heads/maint
</dt>\r
<dd>\r
<p>\r
- Print the parents of the commit.\r
+ Print the parents of the commit. Also enables parent\r
+ rewriting, see <em>History Simplification</em> below.\r
</p>\r
</dd>\r
<dt>\r
</dt>\r
<dd>\r
<p>\r
- Print the children of the commit.\r
+ Print the children of the commit. Also enables parent\r
+ rewriting, see <em>History Simplification</em> below.\r
</p>\r
</dd>\r
<dt>\r
</p>\r
</dd>\r
<dt>\r
---full-history\r
-</dt>\r
-<dd>\r
-<p>\r
- Show also parts of history irrelevant to current state of a given\r
- path. This turns off history simplification, which removed merges\r
- which didn't change anything at all at some child. It will still actually\r
- simplify away merges that didn't change anything at all into either\r
- child.\r
-</p>\r
-</dd>\r
-<dt>\r
--no-merges\r
</dt>\r
<dd>\r
not shown.\r
</p>\r
</dd>\r
+</dl></div>\r
+<h3 id="_history_simplification">History Simplification</h3><div style="clear:left"></div>\r
+<div class="para"><p>When optional paths are given, <em>git-rev-list</em> simplifies commits with\r
+various strategies, according to the options you have selected.</p></div>\r
+<div class="para"><p>Suppose you specified <tt>foo</tt> as the <paths>. We shall call commits\r
+that modify <tt>foo</tt> !TREESAME, and the rest TREESAME. (In a diff\r
+filtered for <tt>foo</tt>, they look different and equal, respectively.)</p></div>\r
+<div class="para"><p>In the following, we will always refer to the same example history to\r
+illustrate the differences between simplification settings. We assume\r
+that you are filtering for a file <tt>foo</tt> in this commit graph:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt> .-A---M---N---O---P\r
+ / / / / /\r
+ I B C D E\r
+ \ / / / /\r
+ `-------------'</tt></pre>\r
+</div></div>\r
+<div class="para"><p>The horizontal line of history A--P is taken to be the first parent of\r
+each merge. The commits are:</p></div>\r
+<div class="ilist"><ul>\r
+<li>\r
+<p>\r
+<tt>I</tt> is the initial commit, in which <tt>foo</tt> exists with contents\r
+ "asdf", and a file <tt>quux</tt> exists with contents "quux". Initial\r
+ commits are compared to an empty tree, so <tt>I</tt> is !TREESAME.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+In <tt>A</tt>, <tt>foo</tt> contains just "foo".\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<tt>B</tt> contains the same change as <tt>A</tt>. Its merge <tt>M</tt> is trivial and\r
+ hence TREESAME to all parents.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<tt>C</tt> does not change <tt>foo</tt>, but its merge <tt>N</tt> changes it to "foobar",\r
+ so it is not TREESAME to any parent.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<tt>D</tt> sets <tt>foo</tt> to "baz". Its merge <tt>O</tt> combines the strings from\r
+ <tt>N</tt> and <tt>D</tt> to "foobarbaz"; i.e., it is not TREESAME to any parent.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<tt>E</tt> changes <tt>quux</tt> to "xyzzy", and its merge <tt>P</tt> combines the\r
+ strings to "quux xyzzy". Despite appearing interesting, <tt>P</tt> is\r
+ TREESAME to all parents.\r
+</p>\r
+</li>\r
+</ul></div>\r
+<div class="para"><p><em>rev-list</em> walks backwards through history, including or excluding\r
+commits based on whether <em>--full-history</em> and/or parent rewriting\r
+(via <em>--parents</em> or <em>--children</em>) are used. The following settings\r
+are available.</p></div>\r
+<div class="vlist"><dl>\r
+<dt>\r
+Default mode\r
+</dt>\r
+<dd>\r
+<p>\r
+ Commits are included if they are not TREESAME to any parent\r
+ (though this can be changed, see <em>--sparse</em> below). If the\r
+ commit was a merge, and it was TREESAME to one parent, follow\r
+ only that parent. (Even if there are several TREESAME\r
+ parents, follow only one of them.) Otherwise, follow all\r
+ parents.\r
+</p>\r
+<div class="para"><p>This results in:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt> .-A---N---O\r
+ / /\r
+ I---------D</tt></pre>\r
+</div></div>\r
+<div class="para"><p>Note how the rule to only follow the TREESAME parent, if one is\r
+available, removed <tt>B</tt> from consideration entirely. <tt>C</tt> was\r
+considered via <tt>N</tt>, but is TREESAME. Root commits are compared to an\r
+empty tree, so <tt>I</tt> is !TREESAME.</p></div>\r
+<div class="para"><p>Parent/child relations are only visible with --parents, but that does\r
+not affect the commits selected in default mode, so we have shown the\r
+parent lines.</p></div>\r
+</dd>\r
+<dt>\r
+--full-history without parent rewriting\r
+</dt>\r
+<dd>\r
+<p>\r
+ This mode differs from the default in one point: always follow\r
+ all parents of a merge, even if it is TREESAME to one of them.\r
+ Even if more than one side of the merge has commits that are\r
+ included, this does not imply that the merge itself is! In\r
+ the example, we get\r
+</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt> I A B N D O</tt></pre>\r
+</div></div>\r
+<div class="para"><p><tt>P</tt> and <tt>M</tt> were excluded because they are TREESAME to a parent. <tt>E</tt>,\r
+<tt>C</tt> and <tt>B</tt> were all walked, but only <tt>B</tt> was !TREESAME, so the others\r
+do not appear.</p></div>\r
+<div class="para"><p>Note that without parent rewriting, it is not really possible to talk\r
+about the parent/child relationships between the commits, so we show\r
+them disconnected.</p></div>\r
+</dd>\r
+<dt>\r
+--full-history with parent rewriting\r
+</dt>\r
+<dd>\r
+<p>\r
+ Ordinary commits are only included if they are !TREESAME\r
+ (though this can be changed, see <em>--sparse</em> below).\r
+</p>\r
+<div class="para"><p>Merges are always included. However, their parent list is rewritten:\r
+Along each parent, prune away commits that are not included\r
+themselves. This results in</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt> .-A---M---N---O---P\r
+ / / / / /\r
+ I B / D /\r
+ \ / / / /\r
+ `-------------'</tt></pre>\r
+</div></div>\r
+<div class="para"><p>Compare to <em>--full-history</em> without rewriting above. Note that <tt>E</tt>\r
+was pruned away because it is TREESAME, but the parent list of P was\r
+rewritten to contain <tt>E</tt>'s parent <tt>I</tt>. The same happened for <tt>C</tt> and\r
+<tt>N</tt>. Note also that <tt>P</tt> was included despite being TREESAME.</p></div>\r
+</dd>\r
+</dl></div>\r
+<div class="para"><p>In addition to the above settings, you can change whether TREESAME\r
+affects inclusion:</p></div>\r
+<div class="vlist"><dl>\r
<dt>\r
--dense\r
</dt>\r
+<dd>\r
+<p>\r
+ Commits that are walked are included if they are not TREESAME\r
+ to any parent.\r
+</p>\r
+</dd>\r
<dt>\r
--sparse\r
</dt>\r
<dd>\r
<p>\r
-When optional paths are given, the default behaviour (<em>--dense</em>) is to\r
-only output commits that changes at least one of them, and also ignore\r
-merges that do not touch the given paths.\r
+ All commits that are walked are included.\r
</p>\r
-<div class="para"><p>Use the <em>--sparse</em> flag to makes the command output all eligible commits\r
-(still subject to count and age limitation), but apply merge\r
-simplification nevertheless.</p></div>\r
+<div class="para"><p>Note that without <em>--full-history</em>, this still simplifies merges: if\r
+one of the parents is TREESAME, we follow only that one, so the other\r
+sides of the merge are never walked.</p></div>\r
</dd>\r
</dl></div>\r
<h3 id="_commit_ordering">Commit Ordering</h3><div style="clear:left"></div>\r
</div>\r
<div id="footer">\r
<div id="footer-text">\r
-Last updated 2008-08-12 06:59:09 UTC\r
+Last updated 2008-08-13 20:03:49 UTC\r
</div>\r
</div>\r
</body>\r
</dt>\r
<dd>\r
<p>\r
- Print the parents of the commit.\r
+ Print the parents of the commit. Also enables parent\r
+ rewriting, see <em>History Simplification</em> below.\r
</p>\r
</dd>\r
<dt>\r
</dt>\r
<dd>\r
<p>\r
- Print the children of the commit.\r
+ Print the children of the commit. Also enables parent\r
+ rewriting, see <em>History Simplification</em> below.\r
</p>\r
</dd>\r
<dt>\r
<em>--date-order</em> option may also be specified.</p></div>\r
</dd>\r
</dl></div>\r
-<h3 id="_diff_formatting">Diff Formatting</h3><div style="clear:left"></div>\r
-<div class="para"><p>Below are listed options that control the formatting of diff output.\r
-Some of them are specific to <a href="git-rev-list.html">git-rev-list(1)</a>, however other diff\r
-options may be given. See <a href="git-diff-files.html">git-diff-files(1)</a> for more options.</p></div>\r
-<div class="vlist"><dl>\r
-<dt>\r
--c\r
-</dt>\r
-<dd>\r
-<p>\r
- This flag changes the way a merge commit is displayed. It shows\r
- the differences from each of the parents to the merge result\r
- simultaneously instead of showing pairwise diff between a parent\r
- and the result one at a time. Furthermore, it lists only files\r
- which were modified from all parents.\r
-</p>\r
-</dd>\r
-<dt>\r
---cc\r
-</dt>\r
-<dd>\r
-<p>\r
- This flag implies the <em>-c</em> options and further compresses the\r
- patch output by omitting uninteresting hunks whose contents in\r
- the parents have only two variants and the merge result picks\r
- one of them without modification.\r
-</p>\r
-</dd>\r
-<dt>\r
--r\r
-</dt>\r
-<dd>\r
-<p>\r
- Show recursive diffs.\r
-</p>\r
-</dd>\r
-<dt>\r
--t\r
-</dt>\r
-<dd>\r
-<p>\r
- Show the tree objects in the diff output. This implies <em>-r</em>.\r
-</p>\r
-</dd>\r
-</dl></div>\r
<h3 id="_commit_limiting">Commit Limiting</h3><div style="clear:left"></div>\r
<div class="para"><p>Besides specifying a range of commits that should be listed using the\r
special notations explained in the description, additional commit\r
</p>\r
</dd>\r
<dt>\r
---full-history\r
-</dt>\r
-<dd>\r
-<p>\r
- Show also parts of history irrelevant to current state of a given\r
- path. This turns off history simplification, which removed merges\r
- which didn't change anything at all at some child. It will still actually\r
- simplify away merges that didn't change anything at all into either\r
- child.\r
-</p>\r
-</dd>\r
-<dt>\r
--no-merges\r
</dt>\r
<dd>\r
not shown.\r
</p>\r
</dd>\r
+</dl></div>\r
+<h3 id="_history_simplification">History Simplification</h3><div style="clear:left"></div>\r
+<div class="para"><p>When optional paths are given, <em>git-rev-list</em> simplifies commits with\r
+various strategies, according to the options you have selected.</p></div>\r
+<div class="para"><p>Suppose you specified <tt>foo</tt> as the <paths>. We shall call commits\r
+that modify <tt>foo</tt> !TREESAME, and the rest TREESAME. (In a diff\r
+filtered for <tt>foo</tt>, they look different and equal, respectively.)</p></div>\r
+<div class="para"><p>In the following, we will always refer to the same example history to\r
+illustrate the differences between simplification settings. We assume\r
+that you are filtering for a file <tt>foo</tt> in this commit graph:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt> .-A---M---N---O---P\r
+ / / / / /\r
+ I B C D E\r
+ \ / / / /\r
+ `-------------'</tt></pre>\r
+</div></div>\r
+<div class="para"><p>The horizontal line of history A--P is taken to be the first parent of\r
+each merge. The commits are:</p></div>\r
+<div class="ilist"><ul>\r
+<li>\r
+<p>\r
+<tt>I</tt> is the initial commit, in which <tt>foo</tt> exists with contents\r
+ "asdf", and a file <tt>quux</tt> exists with contents "quux". Initial\r
+ commits are compared to an empty tree, so <tt>I</tt> is !TREESAME.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+In <tt>A</tt>, <tt>foo</tt> contains just "foo".\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<tt>B</tt> contains the same change as <tt>A</tt>. Its merge <tt>M</tt> is trivial and\r
+ hence TREESAME to all parents.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<tt>C</tt> does not change <tt>foo</tt>, but its merge <tt>N</tt> changes it to "foobar",\r
+ so it is not TREESAME to any parent.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<tt>D</tt> sets <tt>foo</tt> to "baz". Its merge <tt>O</tt> combines the strings from\r
+ <tt>N</tt> and <tt>D</tt> to "foobarbaz"; i.e., it is not TREESAME to any parent.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<tt>E</tt> changes <tt>quux</tt> to "xyzzy", and its merge <tt>P</tt> combines the\r
+ strings to "quux xyzzy". Despite appearing interesting, <tt>P</tt> is\r
+ TREESAME to all parents.\r
+</p>\r
+</li>\r
+</ul></div>\r
+<div class="para"><p><em>rev-list</em> walks backwards through history, including or excluding\r
+commits based on whether <em>--full-history</em> and/or parent rewriting\r
+(via <em>--parents</em> or <em>--children</em>) are used. The following settings\r
+are available.</p></div>\r
+<div class="vlist"><dl>\r
+<dt>\r
+Default mode\r
+</dt>\r
+<dd>\r
+<p>\r
+ Commits are included if they are not TREESAME to any parent\r
+ (though this can be changed, see <em>--sparse</em> below). If the\r
+ commit was a merge, and it was TREESAME to one parent, follow\r
+ only that parent. (Even if there are several TREESAME\r
+ parents, follow only one of them.) Otherwise, follow all\r
+ parents.\r
+</p>\r
+<div class="para"><p>This results in:</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt> .-A---N---O\r
+ / /\r
+ I---------D</tt></pre>\r
+</div></div>\r
+<div class="para"><p>Note how the rule to only follow the TREESAME parent, if one is\r
+available, removed <tt>B</tt> from consideration entirely. <tt>C</tt> was\r
+considered via <tt>N</tt>, but is TREESAME. Root commits are compared to an\r
+empty tree, so <tt>I</tt> is !TREESAME.</p></div>\r
+<div class="para"><p>Parent/child relations are only visible with --parents, but that does\r
+not affect the commits selected in default mode, so we have shown the\r
+parent lines.</p></div>\r
+</dd>\r
+<dt>\r
+--full-history without parent rewriting\r
+</dt>\r
+<dd>\r
+<p>\r
+ This mode differs from the default in one point: always follow\r
+ all parents of a merge, even if it is TREESAME to one of them.\r
+ Even if more than one side of the merge has commits that are\r
+ included, this does not imply that the merge itself is! In\r
+ the example, we get\r
+</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt> I A B N D O</tt></pre>\r
+</div></div>\r
+<div class="para"><p><tt>P</tt> and <tt>M</tt> were excluded because they are TREESAME to a parent. <tt>E</tt>,\r
+<tt>C</tt> and <tt>B</tt> were all walked, but only <tt>B</tt> was !TREESAME, so the others\r
+do not appear.</p></div>\r
+<div class="para"><p>Note that without parent rewriting, it is not really possible to talk\r
+about the parent/child relationships between the commits, so we show\r
+them disconnected.</p></div>\r
+</dd>\r
+<dt>\r
+--full-history with parent rewriting\r
+</dt>\r
+<dd>\r
+<p>\r
+ Ordinary commits are only included if they are !TREESAME\r
+ (though this can be changed, see <em>--sparse</em> below).\r
+</p>\r
+<div class="para"><p>Merges are always included. However, their parent list is rewritten:\r
+Along each parent, prune away commits that are not included\r
+themselves. This results in</p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt> .-A---M---N---O---P\r
+ / / / / /\r
+ I B / D /\r
+ \ / / / /\r
+ `-------------'</tt></pre>\r
+</div></div>\r
+<div class="para"><p>Compare to <em>--full-history</em> without rewriting above. Note that <tt>E</tt>\r
+was pruned away because it is TREESAME, but the parent list of P was\r
+rewritten to contain <tt>E</tt>'s parent <tt>I</tt>. The same happened for <tt>C</tt> and\r
+<tt>N</tt>. Note also that <tt>P</tt> was included despite being TREESAME.</p></div>\r
+</dd>\r
+</dl></div>\r
+<div class="para"><p>In addition to the above settings, you can change whether TREESAME\r
+affects inclusion:</p></div>\r
+<div class="vlist"><dl>\r
<dt>\r
--dense\r
</dt>\r
+<dd>\r
+<p>\r
+ Commits that are walked are included if they are not TREESAME\r
+ to any parent.\r
+</p>\r
+</dd>\r
<dt>\r
--sparse\r
</dt>\r
<dd>\r
<p>\r
-When optional paths are given, the default behaviour (<em>--dense</em>) is to\r
-only output commits that changes at least one of them, and also ignore\r
-merges that do not touch the given paths.\r
+ All commits that are walked are included.\r
</p>\r
-<div class="para"><p>Use the <em>--sparse</em> flag to makes the command output all eligible commits\r
-(still subject to count and age limitation), but apply merge\r
-simplification nevertheless.</p></div>\r
+<div class="para"><p>Note that without <em>--full-history</em>, this still simplifies merges: if\r
+one of the parents is TREESAME, we follow only that one, so the other\r
+sides of the merge are never walked.</p></div>\r
</dd>\r
+</dl></div>\r
+<h3 id="_bisection_helpers">Bisection Helpers</h3><div style="clear:left"></div>\r
+<div class="vlist"><dl>\r
<dt>\r
--bisect\r
</dt>\r
Limit output to the one commit object which is roughly halfway between\r
the included and excluded commits. Thus, if\r
</p>\r
+</dd>\r
+</dl></div>\r
<div class="listingblock">\r
<div class="content">\r
<pre><tt> $ git-rev-list --bisect foo ^bar ^baz</tt></pre>\r
introduces a regression is thus reduced to a binary search: repeatedly\r
generate and test new 'midpoint's until the commit chain is of length\r
one.</p></div>\r
-</dd>\r
+<div class="vlist"><dl>\r
<dt>\r
--bisect-vars\r
</dt>\r
commits. The farthest from them is displayed first. (This is the only\r
one displayed by <tt>--bisect</tt>.)\r
</p>\r
+</dd>\r
+</dl></div>\r
<div class="para"><p>This is useful because it makes it easy to choose a good commit to\r
test when you want to avoid to test some of them for some reason (they\r
may not compile for example).</p></div>\r
<div class="para"><p>This option can be used along with <tt>--bisect-vars</tt>, in this case,\r
after all the sorted commit objects, there will be the same text as if\r
<tt>--bisect-vars</tt> had been used alone.</p></div>\r
-</dd>\r
-</dl></div>\r
<h3 id="_commit_ordering">Commit Ordering</h3><div style="clear:left"></div>\r
<div class="para"><p>By default, the commits are shown in reverse chronological order.</p></div>\r
<div class="vlist"><dl>\r
</div>\r
<div id="footer">\r
<div id="footer-text">\r
-Last updated 2008-08-12 06:59:09 UTC\r
+Last updated 2008-08-13 20:03:49 UTC\r
</div>\r
</div>\r
</body>\r
<div class="para"><p>There are a few built-in patterns to make this easier, and <tt>tex</tt>\r
is one of them, so you do not have to write the above in your\r
configuration file (you still need to enable this with the\r
-attribute mechanism, via <tt>.gitattributes</tt>). Another built-in\r
-pattern is defined for <tt>java</tt> that defines a pattern suitable\r
-for program text in Java language.</p></div>\r
+attribute mechanism, via <tt>.gitattributes</tt>). The following built in\r
+patterns are available:</p></div>\r
+<div class="ilist"><ul>\r
+<li>\r
+<p>\r
+<tt>bibtex</tt> suitable for files with BibTeX coded references.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<tt>java</tt> suitable for source code in the Java lanugage.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<tt>pascal</tt> suitable for source code in the Pascal/Delphi language.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<tt>ruby</tt> suitable for source code in the Ruby language.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<tt>tex</tt> suitable for source code for LaTeX documents.\r
+</p>\r
+</li>\r
+</ul></div>\r
<h3 id="_performing_a_three_way_merge">Performing a three-way merge</h3><div style="clear:left"></div>\r
<div class="para"><p>The attribute <tt>merge</tt> affects how three versions of a file is\r
merged when a file-level merge is necessary during <tt>git merge</tt>,\r
</div>\r
<div id="footer">\r
<div id="footer-text">\r
-Last updated 2008-07-06 05:17:09 UTC\r
+Last updated 2008-08-13 20:03:51 UTC\r
</div>\r
</div>\r
</body>\r
There are a few built-in patterns to make this easier, and `tex`
is one of them, so you do not have to write the above in your
configuration file (you still need to enable this with the
-attribute mechanism, via `.gitattributes`). Another built-in
-pattern is defined for `java` that defines a pattern suitable
-for program text in Java language.
+attribute mechanism, via `.gitattributes`). The following built in
+patterns are available:
+
+- `bibtex` suitable for files with BibTeX coded references.
+
+- `java` suitable for source code in the Java lanugage.
+
+- `pascal` suitable for source code in the Pascal/Delphi language.
+
+- `ruby` suitable for source code in the Ruby language.
+
+- `tex` suitable for source code for LaTeX documents.
Performing a three-way merge
--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.
+ Print the children of the commit. Also enables parent
+ rewriting, see 'History Simplification' below.
ifdef::git-rev-list[]
--timestamp::
This implies the '--topo-order' option by default, but the
'--date-order' option may also be specified.
+ifndef::git-rev-list[]
Diff Formatting
~~~~~~~~~~~~~~~
-t::
Show the tree objects in the diff output. This implies '-r'.
+endif::git-rev-list[]
Commit Limiting
~~~~~~~~~~~~~~~
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.
Output uninteresting commits at the boundary, which are usually
not shown.
+--
+
+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:
+
+* `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.
+
+* 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::
-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.
+ 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.
-Use the '--sparse' flag to makes the command output all eligible commits
-(still subject to count and age limitation), but apply merge
-simplification nevertheless.
ifdef::git-rev-list[]
+Bisection Helpers
+~~~~~~~~~~~~~~~~~
+
--bisect::
Limit output to the one commit object which is roughly halfway between
`--bisect-vars` had been used alone.
endif::git-rev-list[]
---
Commit Ordering
~~~~~~~~~~~~~~~
projects / git.git / commitdiff