Merge branch 'ma/rev-list-options-docfix'
Docfix.
* ma/rev-list-options-docfix:
rev-list-options.txt: start a list for `show-pulls`
diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
index 04ad7dd..b01b2b6 100644
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -581,12 +581,12 @@
Before discussing another option, `--show-pulls`, we need to
create a new example history.
-+
+
A common problem users face when looking at simplified history is that a
commit they know changed a file somehow does not appear in the file's
simplified history. Let's demonstrate a new example and show how options
such as `--full-history` and `--simplify-merges` works in that case:
-+
+
-----------------------------------------------------------------------
.-A---M-----C--N---O---P
/ / \ \ \/ / /
@@ -595,7 +595,7 @@
\ / /\ /
`---X--' `---Y--'
-----------------------------------------------------------------------
-+
+
For this example, suppose `I` created `file.txt` which was modified by
`A`, `B`, and `X` in different ways. The single-parent commits `C`, `Z`,
and `Y` do not change `file.txt`. The merge commit `M` was created by
@@ -607,19 +607,19 @@
contents of `file.txt` at `R`, so `N` is TREESAME to `R` but not `C`.
The merge commits `O` and `P` are TREESAME to their first parents, but
not to their second parents, `Z` and `Y` respectively.
-+
+
When using the default mode, `N` and `R` both have a TREESAME parent, so
those edges are walked and the others are ignored. The resulting history
graph is:
-+
+
-----------------------------------------------------------------------
I---X
-----------------------------------------------------------------------
-+
+
When using `--full-history`, Git walks every edge. This will discover
the commits `A` and `B` and the merge `M`, but also will reveal the
merge commits `O` and `P`. With parent rewriting, the resulting graph is:
-+
+
-----------------------------------------------------------------------
.-A---M--------N---O---P
/ / \ \ \/ / /
@@ -628,21 +628,21 @@
\ / /\ /
`---X--' `------'
-----------------------------------------------------------------------
-+
+
Here, the merge commits `O` and `P` contribute extra noise, as they did
not actually contribute a change to `file.txt`. They only merged a topic
that was based on an older version of `file.txt`. This is a common
issue in repositories using a workflow where many contributors work in
parallel and merge their topic branches along a single trunk: manu
unrelated merges appear in the `--full-history` results.
-+
+
When using the `--simplify-merges` option, the commits `O` and `P`
disappear from the results. This is because the rewritten second parents
of `O` and `P` are reachable from their first parents. Those edges are
removed and then the commits look like single-parent commits that are
TREESAME to their parent. This also happens to the commit `N`, resulting
in a history view as follows:
-+
+
-----------------------------------------------------------------------
.-A---M--.
/ / \
@@ -651,18 +651,18 @@
\ / /
`---X--'
-----------------------------------------------------------------------
-+
+
In this view, we see all of the important single-parent changes from
`A`, `B`, and `X`. We also see the carefully-resolved merge `M` and the
not-so-carefully-resolved merge `R`. This is usually enough information
to determine why the commits `A` and `B` "disappeared" from history in
the default view. However, there are a few issues with this approach.
-+
+
The first issue is performance. Unlike any previous option, the
`--simplify-merges` option requires walking the entire commit history
before returning a single result. This can make the option difficult to
use for very large repositories.
-+
+
The second issue is one of auditing. When many contributors are working
on the same repository, it is important which merge commits introduced
a change into an important branch. The problematic merge `R` above is
@@ -671,10 +671,13 @@
into the important branch. This commit may have information about why
the change `X` came to override the changes from `A` and `B` in its
commit message.
+
+--show-pulls::
+ In addition to the commits shown in the default history, show
+ each merge commit that is not TREESAME to its first parent but
+ is TREESAME to a later parent.
+
-The `--show-pulls` option helps with both of these issues by adding more
-merge commits to the history results. If a merge is not TREESAME to its
-first parent but is TREESAME to a later parent, then that merge is
+When a merge commit is included by `--show-pulls`, the merge is
treated as if it "pulled" the change from another branch. When using
`--show-pulls` on this example (and no other options) the resulting
graph is:
