On 5/17/2020 2:52 PM, Martin Ågren wrote:
> 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::`. But
> we don't have a similar list running here. We could tie all our
> paragraphs from 8d049e182e to that list, but that doesn't make much
> sense: We aim to describe another option entirely.
>
> We could start a new list item:
>
> --show-pulls:
> Before discussing another option, `--show-pulls`, we need to
> create a new example history.
> +
> ...
>
> That reads somewhat awkwardly to me. Not to mention that the chain of
> paragraphs that follows is fairly long, introducing a new example
> history and discussing it in quite some detail. Let's make this run
> along without any kind of indentation. It effectively means that we're
> treating "Before discussing..." as a paragraph on the same level as
> "There is another simplification mode available:" which precedes the
> `--ancestry-path::` list.
>
> If we really want a `--show-pulls::` list somewhere, we could perhaps
> let it begin around "The `--show-pulls` option helps with both of these
> issues ..." further down. But for now, let's just focus on getting rid
> of those literal pluses.
I think the way you adjusted the preamble is good. It matches this prior
work before --ancestry-path:
Finally, there is a fifth simplification mode available:
--ancestry-path::
(description)
+
(example)
+
...
And you're right, we do drop the "--show-pulls::" itemization. Will that
make it hard to link to that exact option? Probably.
What about the fixup below, to create this list item?
Thanks,
-Stolee
-- >8 --
>From 6416bbc14fbdb21868c6f3b609f66e5fe5607265 Mon Sep 17 00:00:00 2001
From: Derrick Stolee <dstolee@xxxxxxxxxxxxx>
Date: Mon, 18 May 2020 10:55:59 -0400
Subject: [PATCH] fixup! rev-list-options.txt
Signed-off-by: Derrick Stolee <dstolee@xxxxxxxxxxxxx>
---
Documentation/rev-list-options.txt | 19 +++++++++++--------
1 file changed, 11 insertions(+), 8 deletions(-)
diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
index 48e37e2456..b01b2b6773 100644
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -672,25 +672,28 @@ 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.
-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
+--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.
++
+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:
-
++
-----------------------------------------------------------------------
I---X---R---N
-----------------------------------------------------------------------
-
++
Here, the merge commits `R` and `N` are included because they pulled
the commits `X` and `R` into the base branch, respectively. These
merges are the reason the commits `A` and `B` do not appear in the
default history.
-
++
When `--show-pulls` is paired with `--simplify-merges`, the
graph includes all of the necessary information:
-
++
-----------------------------------------------------------------------
.-A---M--. N
/ / \ /
@@ -699,7 +702,7 @@ graph includes all of the necessary information:
\ / /
`---X--'
-----------------------------------------------------------------------
-
++
Notice that since `M` is reachable from `R`, the edge from `N` to `M`
was simplified away. However, `N` still appears in the history as an
important commit because it "pulled" the change `R` into the main
--
2.27.0.rc0
