[PATCH v2] rev-list-options.txt: start a list for `show-pulls`

From

MÅMartin Ågren <martin.agren@gmail.com>

Date

May 25, 2020, 17:06 UTC

Message-ID

<20200525170607.8000-1-martin.agren@gmail.com>

In-Reply-To

<xmqqsgfx0z9k.fsf@gitster.c.googlers.com>

On Mon, 18 May 2020 at 22:22, Junio C Hamano <gitster@pobox.com> wrote:

>
> Martin Ågren <martin.agren@gmail.com> writes:
>
> > I currently have the commit message below for my patch plus your fixup.
> > ...
>
> I've queued 1, 3, 4, 5, and 6 in the meantime.  Todd gave us a
> replacement for 2, which I also took.
>
> Thanks.

A long weekend offline passes and it's already a week later...

Martin

Helped-by: Derrick Stolee <stolee@gmail.com>
Signed-off-by: Martin Ågren <martin.agren@gmail.com>
---
 Documentation/rev-list-options.txt | 35 ++++++++++++++++--------------
 1 file changed, 19 insertions(+), 16 deletions(-)

diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
index 04ad7dd36e..b01b2b6773 100644
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -581,12 +581,12 @@ option does. Applied to the 'D..M' range, it results in:
 
 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 @@ such as `--full-history` and `--simplify-merges` works in that case:
 	  \ /      /\        /
 	   `---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 @@ the contents of `file.txt` at `X`. Hence, `R` is TREESAME to `X` but not
 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 @@ merge commits `O` and `P`. With parent rewriting, the resulting graph is:
 	  \ /      /\        /
 	   `---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 @@ in a history view as follows:
 	  \ /      /
 	   `---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 @@ important branch. Instead, the merge `N` was used to merge `R` and `X`
 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:

-- 
2.27.0.rc0