Git Mailing List Archive on
 help / color / Atom feed
From: Derrick Stolee <>
To: "Martin Ågren" <>,
Subject: Re: [PATCH 7/7] rev-list-options.txt
Date: Mon, 18 May 2020 10:57:35 -0400
Message-ID: <> (raw)
In-Reply-To: <>

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:


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?


-- >8 --

From 6416bbc14fbdb21868c6f3b609f66e5fe5607265 Mon Sep 17 00:00:00 2001
From: Derrick Stolee <>
Date: Mon, 18 May 2020 10:55:59 -0400
Subject: [PATCH] fixup! rev-list-options.txt

Signed-off-by: Derrick Stolee <>
 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
+	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:
 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:
 	  \ /      /
 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

  reply index

Thread overview: 24+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-05-17 18:52 [PATCH 0/7] Documentation fixes for v2.27.0-rc0 Martin Ågren
2020-05-17 18:52 ` [PATCH 1/7] date-formats.txt: fix list continuation Martin Ågren
2020-05-17 18:52 ` [PATCH 2/7] git-bugreport.txt: fix reference to strftime(3) Martin Ågren
2020-05-17 19:23   ` Eric Sunshine
2020-05-17 19:27     ` Martin Ågren
2020-05-18 10:54       ` Jean-Noël Avila
2020-05-18 11:15         ` Martin Ågren
2020-05-17 18:52 ` [PATCH 3/7] git-commit-graph.txt: fix grammo Martin Ågren
2020-05-18 14:46   ` Derrick Stolee
2020-05-17 18:52 ` [PATCH 4/7] git-commit-graph.txt: fix list rendering Martin Ågren
2020-05-17 18:52 ` [PATCH 5/7] git-credential.txt: use list continuation Martin Ågren
2020-05-18 23:06   ` Carlo Marcelo Arenas Belón
2020-05-17 18:52 ` [PATCH 6/7] git-sparse-checkout.txt: add missing ' Martin Ågren
2020-05-18 14:46   ` Derrick Stolee
2020-05-17 18:52 ` [PATCH 7/7] rev-list-options.txt Martin Ågren
2020-05-18 14:57   ` Derrick Stolee [this message]
2020-05-18 18:37     ` Martin Ågren
2020-05-18 20:22       ` Junio C Hamano
2020-05-25 17:06         ` [PATCH v2] rev-list-options.txt: start a list for `show-pulls` Martin Ågren
2020-05-26 12:24           ` Derrick Stolee
2020-05-26 19:18             ` Martin Ågren
2020-05-26 15:16           ` Junio C Hamano
2020-05-26 17:01             ` Derrick Stolee
2020-05-26 19:20               ` Martin Ågren

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \ \ \ \ \

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

Git Mailing List Archive on

Archives are clonable:
	git clone --mirror git/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 git git/ \
	public-inbox-index git

Example config snippet for mirrors

Newsgroup available over NNTP:

AGPL code for this site: git clone