Git Mailing List Archive on lore.kernel.org
 help / color / Atom feed
From: Derrick Stolee <stolee@gmail.com>
To: "Martin Ågren" <martin.agren@gmail.com>, git@vger.kernel.org
Subject: Re: [PATCH 7/7] rev-list-options.txt
Date: Mon, 18 May 2020 10:57:35 -0400
Message-ID: <34870e5f-8e61-4af8-1050-43bfbe30d8f9@gmail.com> (raw)
In-Reply-To: <acfca5465e822eaa6f0ddf85a01f7855d3dfb7d1.1589739920.git.martin.agren@gmail.com>

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@microsoft.com>
Date: Mon, 18 May 2020 10:55:59 -0400
Subject: [PATCH] fixup! rev-list-options.txt

Signed-off-by: Derrick Stolee <dstolee@microsoft.com>
---
 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


  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:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

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

  git send-email \
    --in-reply-to=34870e5f-8e61-4af8-1050-43bfbe30d8f9@gmail.com \
    --to=stolee@gmail.com \
    --cc=git@vger.kernel.org \
    --cc=martin.agren@gmail.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

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

Git Mailing List Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/git/0 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/ https://lore.kernel.org/git \
		git@vger.kernel.org
	public-inbox-index git

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.kernel.vger.git


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git