rev-list-options.txt: start a list for `show-pulls`
The explanation of the `--show-pulls` option added in commit 8d049e182e ("revision: --show-pulls adds helpful merges", 2020-04-10) consists of several paragraphs and we use "+" throughout to tie them together in one long chain of list continuations. Only thing is, we're not in any kind of list, so these pluses end up being rendered literally. The preceding few paragraphs describe `--ancestry-path` and there we *do* have a list, since we've started one with `--ancestry-path::`. In fact, we have several such lists for all the various history-simplifying options we're discussing earlier in this file. Thus, we're missing a list both from a consistency point of view and from a practical rendering standpoint. Let's start a list for `--show-pulls` where we start actually discussing the option, and keep the paragraphs preceding it out of that list. That is, drop all those pluses before the new list we're adding here. Helped-by: Derrick Stolee <stolee@gmail.com> Signed-off-by: Martin Ågren <martin.agren@gmail.com> Reviewed-by: Derrick Stolee <dstolee@microsoft.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Martin Ågren committed
May 25, 2020 at 19:06 UTC
32f7037ab31fa2dcf179bc07bf1cea2b732f6543
1 file changed
+19
-16
Documentation/rev-list-options.txt
+19
-16
@@ -581,12 +581,12 @@ option does. Applied to the 'D..M' range, it results in:
581
582
Before discussing another option, `--show-pulls`, we need to
583
create a new example history.
584
-+
584
+
585
A common problem users face when looking at simplified history is that a
586
commit they know changed a file somehow does not appear in the file's
587
simplified history. Let's demonstrate a new example and show how options
588
such as `--full-history` and `--simplify-merges` works in that case:
589
-+
589
+
590
-----------------------------------------------------------------------
591
.-A---M-----C--N---O---P
592
/ / \ \ \/ / /
@@ -595,7 +595,7 @@ such as `--full-history` and `--simplify-merges` works in that case:
595
\ / /\ /
596
`---X--' `---Y--'
597
-----------------------------------------------------------------------
598
-+
598
+
599
For this example, suppose `I` created `file.txt` which was modified by
600
`A`, `B`, and `X` in different ways. The single-parent commits `C`, `Z`,
601
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
607
contents of `file.txt` at `R`, so `N` is TREESAME to `R` but not `C`.
608
The merge commits `O` and `P` are TREESAME to their first parents, but
609
not to their second parents, `Z` and `Y` respectively.
610
-+
610
+
611
When using the default mode, `N` and `R` both have a TREESAME parent, so
612
those edges are walked and the others are ignored. The resulting history
613
graph is:
614
-+
614
+
615
-----------------------------------------------------------------------
616
I---X
617
-----------------------------------------------------------------------
618
-+
618
+
619
When using `--full-history`, Git walks every edge. This will discover
620
the commits `A` and `B` and the merge `M`, but also will reveal the
621
merge commits `O` and `P`. With parent rewriting, the resulting graph is:
622
-+
622
+
623
-----------------------------------------------------------------------
624
.-A---M--------N---O---P
625
/ / \ \ \/ / /
@@ -628,21 +628,21 @@ merge commits `O` and `P`. With parent rewriting, the resulting graph is:
628
\ / /\ /
629
`---X--' `------'
630
-----------------------------------------------------------------------
631
-+
631
+
632
Here, the merge commits `O` and `P` contribute extra noise, as they did
633
not actually contribute a change to `file.txt`. They only merged a topic
634
that was based on an older version of `file.txt`. This is a common
635
issue in repositories using a workflow where many contributors work in
636
parallel and merge their topic branches along a single trunk: manu
637
unrelated merges appear in the `--full-history` results.
638
-+
638
+
639
When using the `--simplify-merges` option, the commits `O` and `P`
640
disappear from the results. This is because the rewritten second parents
641
of `O` and `P` are reachable from their first parents. Those edges are
642
removed and then the commits look like single-parent commits that are
643
TREESAME to their parent. This also happens to the commit `N`, resulting
644
in a history view as follows:
645
-+
645
+
646
-----------------------------------------------------------------------
647
.-A---M--.
648
/ / \
@@ -651,18 +651,18 @@ in a history view as follows:
651
\ / /
652
`---X--'
653
-----------------------------------------------------------------------
654
-+
654
+
655
In this view, we see all of the important single-parent changes from
656
`A`, `B`, and `X`. We also see the carefully-resolved merge `M` and the
657
not-so-carefully-resolved merge `R`. This is usually enough information
658
to determine why the commits `A` and `B` "disappeared" from history in
659
the default view. However, there are a few issues with this approach.
660
-+
660
+
661
The first issue is performance. Unlike any previous option, the
662
`--simplify-merges` option requires walking the entire commit history
663
before returning a single result. This can make the option difficult to
664
use for very large repositories.
665
-+
665
+
666
The second issue is one of auditing. When many contributors are working
667
on the same repository, it is important which merge commits introduced
668
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`
671
into the important branch. This commit may have information about why
672
the change `X` came to override the changes from `A` and `B` in its
673
commit message.
674
+
675
+--show-pulls::
676
+ In addition to the commits shown in the default history, show
677
+ each merge commit that is not TREESAME to its first parent but
678
+ is TREESAME to a later parent.
679
+
675
-The `--show-pulls` option helps with both of these issues by adding more
676
-merge commits to the history results. If a merge is not TREESAME to its
677
-first parent but is TREESAME to a later parent, then that merge is
680
+When a merge commit is included by `--show-pulls`, the merge is
681
treated as if it "pulled" the change from another branch. When using
682
`--show-pulls` on this example (and no other options) the resulting
683
graph is: