{"thread":{"id":"53490","subject":"[PATCH 0/7] Documentation fixes for v2.27.0-rc0","startedAt":"2020-05-17T18:52:34Z","lastAt":"2020-05-26T19:20:35Z","messageCount":24,"participants":["Martin Ågren","Eric Sunshine","Jean-Noël Avila","Derrick Stolee","Junio C Hamano","Carlo Marcelo Arenas Belón"],"isPatch":true,"patchVersion":1,"patchTotal":7},"messages":[{"id":"398019","messageId":"cover.1589739920.git.martin.agren@gmail.com","threadId":"53490","inReplyTo":null,"subject":"[PATCH 0/7] Documentation fixes for v2.27.0-rc0","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2020-05-17T18:52:15Z","receivedAt":"2020-05-17T18:52:34Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"I've gone through\n\n doc-diff v2.26.0 v2.27.0-rc0\n\nand identified a few misrenderings. Here's my attempt to address them.\n\nWorking on this, I also got to look at the new features in the upcoming\nrelease from another angle -- looking good!\n\nMartin Ågren (7):\n date-formats.txt: fix list continuation\n git-bugreport.txt: fix reference to strftime(3)\n git-commit-graph.txt: fix grammo\n git-commit-graph.txt: fix list rendering\n git-credential.txt: use list continuation\n git-sparse-checkout.txt: add missing '\n rev-list-options.txt\n\n Documentation/date-formats.txt | 3 +--\n Documentation/git-bugreport.txt | 2 +-\n Documentation/git-commit-graph.txt | 3 ++-\n Documentation/git-credential.txt | 16 +++++------\n Documentation/git-sparse-checkout.txt | 2 +-\n Documentation/rev-list-options.txt | 38 +++++++++++++--------------\n 6 files changed, 32 insertions(+), 32 deletions(-)\n\n-- \n2.27.0.rc0\n\n"},{"id":"398020","messageId":"63c07d03a471addff3e98bb7ec669f7224cf6e24.1589739920.git.martin.agren@gmail.com","threadId":"53490","inReplyTo":"cover.1589739920.git.martin.agren@gmail.com","subject":"[PATCH 1/7] date-formats.txt: fix list continuation","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2020-05-17T18:52:16Z","receivedAt":"2020-05-17T18:52:35Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"The blank line before the lone \"+\" means it isn't detected as a list\ncontinuation, but instead renders literally, at least with AsciiDoc.\nDrop the empty line and, while at it, add a closing period to the\npreceding paragraph.\n\nSigned-off-by: Martin Ågren \n---\n Documentation/date-formats.txt | 3 +--\n 1 file changed, 1 insertion(+), 2 deletions(-)\n\ndiff --git a/Documentation/date-formats.txt b/Documentation/date-formats.txt\nindex 7e7eaba643..f1097fac69 100644\n--- a/Documentation/date-formats.txt\n+++ b/Documentation/date-formats.txt\n@@ -22,8 +22,7 @@ ISO 8601::\n \t`2005-04-07T22:13:13`. The parser accepts a space instead of the\n \t`T` character as well. Fractional parts of a second will be ignored,\n \tfor example `2005-04-07T22:13:13.019` will be treated as\n-\t`2005-04-07T22:13:13`\n-\n+\t`2005-04-07T22:13:13`.\n +\n NOTE: In addition, the date part is accepted in the following formats:\n `YYYY.MM.DD`, `MM/DD/YYYY` and `DD.MM.YYYY`.\n-- \n2.27.0.rc0\n\n"},{"id":"398021","messageId":"4753804d23ba7b1b267b6557077c80f3a8891712.1589739920.git.martin.agren@gmail.com","threadId":"53490","inReplyTo":"cover.1589739920.git.martin.agren@gmail.com","subject":"[PATCH 2/7] git-bugreport.txt: fix reference to strftime(3)","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2020-05-17T18:52:17Z","receivedAt":"2020-05-17T18:52:38Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"When we say \"link:strftime[3]\", it ends up rendered as \"3[1]\" and we\nproduce a footnote referring to the non-existing\nfile:///.../git-doc/strftime. Make sure we use gitlink, not link, to get\nthe effect we're after.\n\nSigned-off-by: Martin Ågren \n---\n Documentation/git-bugreport.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-bugreport.txt b/Documentation/git-bugreport.txt\nindex 7fe9aef34e..5ee9988628 100644\n--- a/Documentation/git-bugreport.txt\n+++ b/Documentation/git-bugreport.txt\n@@ -46,7 +46,7 @@ OPTIONS\n --suffix ::\n \tSpecify an alternate suffix for the bugreport name, to create a file\n \tnamed 'git-bugreport-'. This should take the form of a\n-\tlink:strftime[3] format string; the current local time will be used.\n+\tlinkgit:strftime[3] format string; the current local time will be used.\n \n GIT\n ---\n-- \n2.27.0.rc0\n\n"},{"id":"398022","messageId":"af1e7c7d7d123d1187a7ef62cbf11fc41ce2fdc7.1589739920.git.martin.agren@gmail.com","threadId":"53490","inReplyTo":"cover.1589739920.git.martin.agren@gmail.com","subject":"[PATCH 3/7] git-commit-graph.txt: fix grammo","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2020-05-17T18:52:18Z","receivedAt":"2020-05-17T18:52:40Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"It's easy to mix up the possessive \"its\" and \"it's\" (\"it is\"). Correct\nan instance of this.\n\nSigned-off-by: Martin Ågren \n---\n Documentation/git-commit-graph.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt\nindex 53a650225a..258bf66e46 100644\n--- a/Documentation/git-commit-graph.txt\n+++ b/Documentation/git-commit-graph.txt\n@@ -58,7 +58,7 @@ With the `--append` option, include all commits that are present in the\n existing commit-graph file.\n +\n With the `--changed-paths` option, compute and write information about the\n-paths changed between a commit and it's first parent. This operation can\n+paths changed between a commit and its first parent. This operation can\n take a while on large repositories. It provides significant performance gains\n for getting history of a directory or a file with `git log -- `.\n +\n-- \n2.27.0.rc0\n\n"},{"id":"398023","messageId":"8203fc4c118eb3bd18e0632ffb9e1a618ae383c7.1589739920.git.martin.agren@gmail.com","threadId":"53490","inReplyTo":"cover.1589739920.git.martin.agren@gmail.com","subject":"[PATCH 4/7] git-commit-graph.txt: fix list rendering","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2020-05-17T18:52:19Z","receivedAt":"2020-05-17T18:52:41Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"The first list item follows immediately on the paragraph where we\nintroduce the list. This makes the \"*\" render literally as part of one\nhuge paragraph. (With AsciiDoc, everything is fine after that, but with\nAsciidoctor, we get some minor follow-on errors.) Add an empty line --\nwith a list continuation (\"+\") -- to make the first list item render ok.\n\nSigned-off-by: Martin Ågren \n---\n Documentation/git-commit-graph.txt | 1 +\n 1 file changed, 1 insertion(+)\n\ndiff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt\nindex 258bf66e46..a3d996787b 100644\n--- a/Documentation/git-commit-graph.txt\n+++ b/Documentation/git-commit-graph.txt\n@@ -68,6 +68,7 @@ chain of multiple commit-graph files stored in\n strategy and other splitting options. The new commits not already in the\n commit-graph are added in a new \"tip\" file. This file is merged with the\n existing file if the following merge conditions are met:\n++\n * If `--split=no-merge` is specified, a merge is never performed, and\n the remaining options are ignored. `--split=replace` overwrites the\n existing chain with a new one. A bare `--split` defers to the remaining\n-- \n2.27.0.rc0\n\n"},{"id":"398024","messageId":"e60236e18f73dcabce1a20ec17aee57fd54b11c9.1589739920.git.martin.agren@gmail.com","threadId":"53490","inReplyTo":"cover.1589739920.git.martin.agren@gmail.com","subject":"[PATCH 5/7] git-credential.txt: use list continuation","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2020-05-17T18:52:20Z","receivedAt":"2020-05-17T18:52:43Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"Use list continuation to avoid the second and third paragraphs\nrendering with a different indentation from the first one where we\ndescribe the \"url\" attribute.\n\nSigned-off-by: Martin Ågren \n---\n Documentation/git-credential.txt | 16 ++++++++--------\n 1 file changed, 8 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/git-credential.txt b/Documentation/git-credential.txt\nindex 8d990e92fd..31c81c4c02 100644\n--- a/Documentation/git-credential.txt\n+++ b/Documentation/git-credential.txt\n@@ -151,11 +151,11 @@ Git understands the following attributes:\n \twere read (e.g., `url=https://example.com` would behave as if\n \t`protocol=https` and `host=example.com` had been provided). This\n \tcan help callers avoid parsing URLs themselves.\n-\n-\tNote that specifying a protocol is mandatory and if the URL\n-\tdoesn't specify a hostname (e.g., \"cert:///path/to/file\") the\n-\tcredential will contain a hostname attribute whose value is an\n-\tempty string.\n-\n-\tComponents which are missing from the URL (e.g., there is no\n-\tusername in the example above) will be left unset.\n++\n+Note that specifying a protocol is mandatory and if the URL\n+doesn't specify a hostname (e.g., \"cert:///path/to/file\") the\n+credential will contain a hostname attribute whose value is an\n+empty string.\n++\n+Components which are missing from the URL (e.g., there is no\n+username in the example above) will be left unset.\n-- \n2.27.0.rc0\n\n"},{"id":"398025","messageId":"69faf4d317547143f455321c5a70575cb7b0b0ad.1589739920.git.martin.agren@gmail.com","threadId":"53490","inReplyTo":"cover.1589739920.git.martin.agren@gmail.com","subject":"[PATCH 6/7] git-sparse-checkout.txt: add missing '","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2020-05-17T18:52:21Z","receivedAt":"2020-05-17T18:52:44Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"Where we explain the 'reapply' command, we don't properly wrap it in\nsingle quote marks like we do with the other commands: We omit the\nclosing mark (\"'reapply\") and this ends up being rendered literally as\n\"'reapply\". Add the missing \"'\".\n\nSigned-off-by: Martin Ågren \n---\n Documentation/git-sparse-checkout.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt\nindex 1a3ace6082..7c8943af7a 100644\n--- a/Documentation/git-sparse-checkout.txt\n+++ b/Documentation/git-sparse-checkout.txt\n@@ -70,7 +70,7 @@ C-style quoted strings.\n \t`core.sparseCheckoutCone` is enabled, the given patterns are interpreted\n \tas directory names as in the 'set' subcommand.\n \n-'reapply::\n+'reapply'::\n \tReapply the sparsity pattern rules to paths in the working tree.\n \tCommands like merge or rebase can materialize paths to do their\n \twork (e.g. in order to show you a conflict), and other\n-- \n2.27.0.rc0\n\n"},{"id":"398026","messageId":"acfca5465e822eaa6f0ddf85a01f7855d3dfb7d1.1589739920.git.martin.agren@gmail.com","threadId":"53490","inReplyTo":"cover.1589739920.git.martin.agren@gmail.com","subject":"[PATCH 7/7] rev-list-options.txt","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2020-05-17T18:52:22Z","receivedAt":"2020-05-17T18:52:46Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"The explanation of the `--show-pulls` option added in commit 8d049e182e\n(\"revision: --show-pulls adds helpful merges\", 2020-04-10) consists of\nseveral paragraphs and we use \"+\" throughout to tie them together in one\nlong chain of list continuations. Only thing is, we're not in any kind\nof list, so these pluses end up being rendered literally.\n\nThe preceding few paragraphs describe `--ancestry-path` and there we\n*do* have a list, since we've started one with `--ancestry-path::`. But\nwe don't have a similar list running here. We could tie all our\nparagraphs from 8d049e182e to that list, but that doesn't make much\nsense: We aim to describe another option entirely.\n\nWe could start a new list item:\n\n --show-pulls:\n Before discussing another option, `--show-pulls`, we need to\n create a new example history.\n +\n ...\n\nThat reads somewhat awkwardly to me. Not to mention that the chain of\nparagraphs that follows is fairly long, introducing a new example\nhistory and discussing it in quite some detail. Let's make this run\nalong without any kind of indentation. It effectively means that we're\ntreating \"Before discussing...\" as a paragraph on the same level as\n\"There is another simplification mode available:\" which precedes the\n`--ancestry-path::` list.\n\nIf we really want a `--show-pulls::` list somewhere, we could perhaps\nlet it begin around \"The `--show-pulls` option helps with both of these\nissues ...\" further down. But for now, let's just focus on getting rid\nof those literal pluses.\n\nSigned-off-by: Martin Ågren \n---\n Documentation/rev-list-options.txt | 38 +++++++++++++++---------------\n 1 file changed, 19 insertions(+), 19 deletions(-)\n\ndiff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt\nindex 04ad7dd36e..48e37e2456 100644\n--- a/Documentation/rev-list-options.txt\n+++ b/Documentation/rev-list-options.txt\n@@ -581,12 +581,12 @@ option does. Applied to the 'D..M' range, it results in:\n \n Before discussing another option, `--show-pulls`, we need to\n create a new example history.\n-+\n+\n A common problem users face when looking at simplified history is that a\n commit they know changed a file somehow does not appear in the file's\n simplified history. Let's demonstrate a new example and show how options\n such as `--full-history` and `--simplify-merges` works in that case:\n-+\n+\n -----------------------------------------------------------------------\n \t .-A---M-----C--N---O---P\n \t / / \\ \\ \\/ / /\n@@ -595,7 +595,7 @@ such as `--full-history` and `--simplify-merges` works in that case:\n \t \\ / /\\ /\n \t `---X--' `---Y--'\n -----------------------------------------------------------------------\n-+\n+\n For this example, suppose `I` created `file.txt` which was modified by\n `A`, `B`, and `X` in different ways. The single-parent commits `C`, `Z`,\n and `Y` do not change `file.txt`. The merge commit `M` was created by\n@@ -607,19 +607,19 @@ the contents of `file.txt` at `X`. Hence, `R` is TREESAME to `X` but not\n contents of `file.txt` at `R`, so `N` is TREESAME to `R` but not `C`.\n The merge commits `O` and `P` are TREESAME to their first parents, but\n not to their second parents, `Z` and `Y` respectively.\n-+\n+\n When using the default mode, `N` and `R` both have a TREESAME parent, so\n those edges are walked and the others are ignored. The resulting history\n graph is:\n-+\n+\n -----------------------------------------------------------------------\n \tI---X\n -----------------------------------------------------------------------\n-+\n+\n When using `--full-history`, Git walks every edge. This will discover\n the commits `A` and `B` and the merge `M`, but also will reveal the\n merge commits `O` and `P`. With parent rewriting, the resulting graph is:\n-+\n+\n -----------------------------------------------------------------------\n \t .-A---M--------N---O---P\n \t / / \\ \\ \\/ / /\n@@ -628,21 +628,21 @@ merge commits `O` and `P`. With parent rewriting, the resulting graph is:\n \t \\ / /\\ /\n \t `---X--' `------'\n -----------------------------------------------------------------------\n-+\n+\n Here, the merge commits `O` and `P` contribute extra noise, as they did\n not actually contribute a change to `file.txt`. They only merged a topic\n that was based on an older version of `file.txt`. This is a common\n issue in repositories using a workflow where many contributors work in\n parallel and merge their topic branches along a single trunk: manu\n unrelated merges appear in the `--full-history` results.\n-+\n+\n When using the `--simplify-merges` option, the commits `O` and `P`\n disappear from the results. This is because the rewritten second parents\n of `O` and `P` are reachable from their first parents. Those edges are\n removed and then the commits look like single-parent commits that are\n TREESAME to their parent. This also happens to the commit `N`, resulting\n in a history view as follows:\n-+\n+\n -----------------------------------------------------------------------\n \t .-A---M--.\n \t / / \\\n@@ -651,18 +651,18 @@ in a history view as follows:\n \t \\ / /\n \t `---X--'\n -----------------------------------------------------------------------\n-+\n+\n In this view, we see all of the important single-parent changes from\n `A`, `B`, and `X`. We also see the carefully-resolved merge `M` and the\n not-so-carefully-resolved merge `R`. This is usually enough information\n to determine why the commits `A` and `B` \"disappeared\" from history in\n the default view. However, there are a few issues with this approach.\n-+\n+\n The first issue is performance. Unlike any previous option, the\n `--simplify-merges` option requires walking the entire commit history\n before returning a single result. This can make the option difficult to\n use for very large repositories.\n-+\n+\n The second issue is one of auditing. When many contributors are working\n on the same repository, it is important which merge commits introduced\n a change into an important branch. The problematic merge `R` above is\n@@ -671,26 +671,26 @@ important branch. Instead, the merge `N` was used to merge `R` and `X`\n into the important branch. This commit may have information about why\n the change `X` came to override the changes from `A` and `B` in its\n commit message.\n-+\n+\n The `--show-pulls` option helps with both of these issues by adding more\n merge commits to the history results. If a merge is not TREESAME to its\n first parent but is TREESAME to a later parent, then that merge is\n treated as if it \"pulled\" the change from another branch. When using\n `--show-pulls` on this example (and no other options) the resulting\n graph is:\n-+\n+\n -----------------------------------------------------------------------\n \tI---X---R---N\n -----------------------------------------------------------------------\n-+\n+\n Here, the merge commits `R` and `N` are included because they pulled\n the commits `X` and `R` into the base branch, respectively. These\n merges are the reason the commits `A` and `B` do not appear in the\n default history.\n-+\n+\n When `--show-pulls` is paired with `--simplify-merges`, the\n graph includes all of the necessary information:\n-+\n+\n -----------------------------------------------------------------------\n \t .-A---M--. N\n \t / / \\ /\n@@ -699,7 +699,7 @@ graph includes all of the necessary information:\n \t \\ / /\n \t `---X--'\n -----------------------------------------------------------------------\n-+\n+\n Notice that since `M` is reachable from `R`, the edge from `N` to `M`\n was simplified away. However, `N` still appears in the history as an\n important commit because it \"pulled\" the change `R` into the main\n-- \n2.27.0.rc0\n\n"},{"id":"398027","messageId":"CAPig+cTMrdeBLzUKKpkuZgSbXULhQb4epNC5qMMTUgqfZ1a0bA@mail.gmail.com","threadId":"53490","inReplyTo":"4753804d23ba7b1b267b6557077c80f3a8891712.1589739920.git.martin.agren@gmail.com","subject":"Re: [PATCH 2/7] git-bugreport.txt: fix reference to strftime(3)","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2020-05-17T19:23:28Z","receivedAt":"2020-05-17T19:23:42Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Sun, May 17, 2020 at 2:52 PM Martin Ågren wrote:\n> When we say \"link:strftime[3]\", it ends up rendered as \"3[1]\" and we\n> produce a footnote referring to the non-existing\n> file:///.../git-doc/strftime. Make sure we use gitlink, not link, to get\n\ns/gitlink/linkgit/\n\n> the effect we're after.\n>\n> Signed-off-by: Martin Ågren \n"},{"id":"398028","messageId":"CAN0heSqkGnYpOvzym+fv6_2_791j6jRwyWMpG9hG4H2KfY6BRQ@mail.gmail.com","threadId":"53490","inReplyTo":"CAPig+cTMrdeBLzUKKpkuZgSbXULhQb4epNC5qMMTUgqfZ1a0bA@mail.gmail.com","subject":"Re: [PATCH 2/7] git-bugreport.txt: fix reference to strftime(3)","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2020-05-17T19:27:10Z","receivedAt":"2020-05-17T19:27:23Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On Sun, 17 May 2020 at 21:23, Eric Sunshine wrote:\n>\n> On Sun, May 17, 2020 at 2:52 PM Martin Ågren wrote:\n> > When we say \"link:strftime[3]\", it ends up rendered as \"3[1]\" and we\n> > produce a footnote referring to the non-existing\n> > file:///.../git-doc/strftime. Make sure we use gitlink, not link, to get\n>\n> s/gitlink/linkgit/\n\nOops, thanks! At least the diff is correct.\n\nMartin\n"},{"id":"398063","messageId":"96735cc6-35d6-f94d-75d5-d6d4df1aefa0@gmail.com","threadId":"53490","inReplyTo":"CAN0heSqkGnYpOvzym+fv6_2_791j6jRwyWMpG9hG4H2KfY6BRQ@mail.gmail.com","subject":"Re: [PATCH 2/7] git-bugreport.txt: fix reference to strftime(3)","fromName":"Jean-Noël Avila","fromEmail":"avila.jn@gmail.com","sentAt":"2020-05-18T10:54:56Z","receivedAt":"2020-05-18T10:55:01Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"On Mon, 18 May 2020, Martin Ågren, Eric Sunshine wrote:\n> On Sun, 17 May 2020 at 21:23, Eric Sunshine wrote:\n>> On Sun, May 17, 2020 at 2:52 PM Martin Ågren wrote:\n>>> When we say \"link:strftime[3]\", it ends up rendered as \"3[1]\" and we\n>>> produce a footnote referring to the non-existing\n>>> file:///.../git-doc/strftime. Make sure we use gitlink, not link, to get\n>> s/gitlink/linkgit/\n> Oops, thanks! At least the diff is correct.\n>\n> Martin\n\nNot even sure of that: strftime is not an internal manpage, so for html\ntarget, we will end up with a hyperlink to an non-existing file\nstrftime.html. So I would keep it as simple text.\n\n\nJN\n\n\n\n\n"},{"id":"398064","messageId":"CAN0heSpu7yjB0aJRuRhU+dncDryTRkMq4+B_D4BHBav5YoD1gw@mail.gmail.com","threadId":"53490","inReplyTo":"96735cc6-35d6-f94d-75d5-d6d4df1aefa0@gmail.com","subject":"Re: [PATCH 2/7] git-bugreport.txt: fix reference to strftime(3)","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2020-05-18T11:15:49Z","receivedAt":"2020-05-18T11:15:39Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On Mon, 18 May 2020 at 12:54, Jean-Noël Avila wrote:\n>\n> On Mon, 18 May 2020, Martin Ågren, Eric Sunshine wrote:\n> > On Sun, 17 May 2020 at 21:23, Eric Sunshine wrote:\n> >> On Sun, May 17, 2020 at 2:52 PM Martin Ågren wrote:\n> >>> When we say \"link:strftime[3]\", it ends up rendered as \"3[1]\" and we\n> >>> produce a footnote referring to the non-existing\n> >>> file:///.../git-doc/strftime. Make sure we use gitlink, not link, to get\n> >> s/gitlink/linkgit/\n\n> > Oops, thanks! At least the diff is correct.\n>\n> Not even sure of that: strftime is not an internal manpage, so for html\n> target, we will end up with a hyperlink to an non-existing file\n> strftime.html. So I would keep it as simple text.\n\nThat's a good point. I don't use the HTML versions myself, so I haven't\nthought about the *linking* nature much -- I just see the formatting.\nBut you're right. Grepping around, we only seem to use linkgit to refer\nto our own docs. So this should probably just be \"strftime(3)\" as you\nsay.\n\nThanks,\nMartin\n"},{"id":"398072","messageId":"f2e465e4-4671-6bcb-144e-5b9ccb95e419@gmail.com","threadId":"53490","inReplyTo":"af1e7c7d7d123d1187a7ef62cbf11fc41ce2fdc7.1589739920.git.martin.agren@gmail.com","subject":"Re: [PATCH 3/7] git-commit-graph.txt: fix grammo","fromName":"Derrick Stolee","fromEmail":"stolee@gmail.com","sentAt":"2020-05-18T14:46:04Z","receivedAt":"2020-05-18T14:46:08Z","isPatch":true,"sender":{"key":"stolee@gmail.com","avatar":"https://avatars.githubusercontent.com/u/570044?v=4"},"body":"On 5/17/2020 2:52 PM, Martin Ågren wrote:\n> It's easy to mix up the possessive \"its\" and \"it's\" (\"it is\"). Correct\n> an instance of this.\n\nGood catch. Thanks!\n\n-Stolee\n"},{"id":"398073","messageId":"9d53f615-bb97-bd93-c72b-738a416c8217@gmail.com","threadId":"53490","inReplyTo":"69faf4d317547143f455321c5a70575cb7b0b0ad.1589739920.git.martin.agren@gmail.com","subject":"Re: [PATCH 6/7] git-sparse-checkout.txt: add missing '","fromName":"Derrick Stolee","fromEmail":"stolee@gmail.com","sentAt":"2020-05-18T14:46:45Z","receivedAt":"2020-05-18T14:46:50Z","isPatch":true,"sender":{"key":"stolee@gmail.com","avatar":"https://avatars.githubusercontent.com/u/570044?v=4"},"body":"On 5/17/2020 2:52 PM, Martin Ågren wrote:\n> Where we explain the 'reapply' command, we don't properly wrap it in\n> single quote marks like we do with the other commands: We omit the\n> closing mark (\"'reapply\") and this ends up being rendered literally as\n> \"'reapply\". Add the missing \"'\".\n> \n> Signed-off-by: Martin Ågren \n> ---\n> Documentation/git-sparse-checkout.txt | 2 +-\n> 1 file changed, 1 insertion(+), 1 deletion(-)\n> \n> diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt\n> index 1a3ace6082..7c8943af7a 100644\n> --- a/Documentation/git-sparse-checkout.txt\n> +++ b/Documentation/git-sparse-checkout.txt\n> @@ -70,7 +70,7 @@ C-style quoted strings.\n> \t`core.sparseCheckoutCone` is enabled, the given patterns are interpreted\n> \tas directory names as in the 'set' subcommand.\n> \n> -'reapply::\n> +'reapply'::\n\nSubtle! But good catch. Thanks!\n\n-Stolee\n\n"},{"id":"398075","messageId":"34870e5f-8e61-4af8-1050-43bfbe30d8f9@gmail.com","threadId":"53490","inReplyTo":"acfca5465e822eaa6f0ddf85a01f7855d3dfb7d1.1589739920.git.martin.agren@gmail.com","subject":"Re: [PATCH 7/7] rev-list-options.txt","fromName":"Derrick Stolee","fromEmail":"stolee@gmail.com","sentAt":"2020-05-18T14:57:35Z","receivedAt":"2020-05-18T14:57:41Z","isPatch":true,"sender":{"key":"stolee@gmail.com","avatar":"https://avatars.githubusercontent.com/u/570044?v=4"},"body":"On 5/17/2020 2:52 PM, Martin Ågren wrote:\n> The explanation of the `--show-pulls` option added in commit 8d049e182e\n> (\"revision: --show-pulls adds helpful merges\", 2020-04-10) consists of\n> several paragraphs and we use \"+\" throughout to tie them together in one\n> long chain of list continuations. Only thing is, we're not in any kind\n> of list, so these pluses end up being rendered literally.\n> \n> The preceding few paragraphs describe `--ancestry-path` and there we\n> *do* have a list, since we've started one with `--ancestry-path::`. But\n> we don't have a similar list running here. We could tie all our\n> paragraphs from 8d049e182e to that list, but that doesn't make much\n> sense: We aim to describe another option entirely.\n> \n> We could start a new list item:\n> \n> --show-pulls:\n> Before discussing another option, `--show-pulls`, we need to\n> create a new example history.\n> +\n> ...\n> \n> That reads somewhat awkwardly to me. Not to mention that the chain of\n> paragraphs that follows is fairly long, introducing a new example\n> history and discussing it in quite some detail. Let's make this run\n> along without any kind of indentation. It effectively means that we're\n> treating \"Before discussing...\" as a paragraph on the same level as\n> \"There is another simplification mode available:\" which precedes the\n> `--ancestry-path::` list.\n> \n> If we really want a `--show-pulls::` list somewhere, we could perhaps\n> let it begin around \"The `--show-pulls` option helps with both of these\n> issues ...\" further down. But for now, let's just focus on getting rid\n> of those literal pluses.\n\nI think the way you adjusted the preamble is good. It matches this prior\nwork before --ancestry-path:\n\n\tFinally, there is a fifth simplification mode available:\n\n\t--ancestry-path::\n\t\t(description)\n\t+\n\t(example)\n\t+\n\t...\n\nAnd you're right, we do drop the \"--show-pulls::\" itemization. Will that\nmake it hard to link to that exact option? Probably.\n\nWhat about the fixup below, to create this list item?\n\nThanks,\n-Stolee\n\n-- >8 --\n\nFrom 6416bbc14fbdb21868c6f3b609f66e5fe5607265 Mon Sep 17 00:00:00 2001\nFrom: Derrick Stolee \nDate: Mon, 18 May 2020 10:55:59 -0400\nSubject: [PATCH] fixup! rev-list-options.txt\n\nSigned-off-by: Derrick Stolee \n---\n Documentation/rev-list-options.txt | 19 +++++++++++--------\n 1 file changed, 11 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt\nindex 48e37e2456..b01b2b6773 100644\n--- a/Documentation/rev-list-options.txt\n+++ b/Documentation/rev-list-options.txt\n@@ -672,25 +672,28 @@ into the important branch. This commit may have information about why\n the change `X` came to override the changes from `A` and `B` in its\n commit message.\n \n-The `--show-pulls` option helps with both of these issues by adding more\n-merge commits to the history results. If a merge is not TREESAME to its\n-first parent but is TREESAME to a later parent, then that merge is\n+--show-pulls::\n+\tIn addition to the commits shown in the default history, show\n+\teach merge commit that is not TREESAME to its first parent but\n+\tis TREESAME to a later parent.\n++\n+When a merge commit is included by `--show-pulls`, the merge is\n treated as if it \"pulled\" the change from another branch. When using\n `--show-pulls` on this example (and no other options) the resulting\n graph is:\n-\n++\n -----------------------------------------------------------------------\n \tI---X---R---N\n -----------------------------------------------------------------------\n-\n++\n Here, the merge commits `R` and `N` are included because they pulled\n the commits `X` and `R` into the base branch, respectively. These\n merges are the reason the commits `A` and `B` do not appear in the\n default history.\n-\n++\n When `--show-pulls` is paired with `--simplify-merges`, the\n graph includes all of the necessary information:\n-\n++\n -----------------------------------------------------------------------\n \t .-A---M--. N\n \t / / \\ /\n@@ -699,7 +702,7 @@ graph includes all of the necessary information:\n \t \\ / /\n \t `---X--'\n -----------------------------------------------------------------------\n-\n++\n Notice that since `M` is reachable from `R`, the edge from `N` to `M`\n was simplified away. However, `N` still appears in the history as an\n important commit because it \"pulled\" the change `R` into the main\n-- \n2.27.0.rc0\n\n"},{"id":"398123","messageId":"CAN0heSo_Y2Esp8X_amPXKaGaOVbP5rnJAyXiuUuW5BFSmwzhwA@mail.gmail.com","threadId":"53490","inReplyTo":"34870e5f-8e61-4af8-1050-43bfbe30d8f9@gmail.com","subject":"Re: [PATCH 7/7] rev-list-options.txt","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2020-05-18T18:37:14Z","receivedAt":"2020-05-18T18:37:30Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"Hi Stolee,\n\n(I realize now that the subject/oneliner of this patch is completely\nbroken. Hmpf.)\n\nOn Mon, 18 May 2020 at 16:57, Derrick Stolee wrote:\n>\n> On 5/17/2020 2:52 PM, Martin Ågren wrote:\n> > If we really want a `--show-pulls::` list somewhere, we could perhaps\n> > let it begin around \"The `--show-pulls` option helps with both of these\n> > issues ...\" further down. But for now, let's just focus on getting rid\n> > of those literal pluses.\n>\n> I think the way you adjusted the preamble is good. It matches this prior\n> work before --ancestry-path:\n>\n> Finally, there is a fifth simplification mode available:\n>\n> --ancestry-path::\n> (description)\n> +\n> (example)\n> +\n> ...\n>\n> And you're right, we do drop the \"--show-pulls::\" itemization. Will that\n> make it hard to link to that exact option? Probably.\n>\n> What about the fixup below, to create this list item?\n\nI considered creating the list item, but like you, I figured it required\nmore surgery to the text than I felt like pursuing. Thanks for making a\nconcrete suggestion.\n\n> -The `--show-pulls` option helps with both of these issues by adding more\n> -merge commits to the history results. If a merge is not TREESAME to its\n> -first parent but is TREESAME to a later parent, then that merge is\n> +--show-pulls::\n> + In addition to the commits shown in the default history, show\n> + each merge commit that is not TREESAME to its first parent but\n> + is TREESAME to a later parent.\n> ++\n> +When a merge commit is included by `--show-pulls`, the merge is\n> treated as if it \"pulled\" the change from another branch. When using\n> `--show-pulls` on this example (and no other options) the resulting\n> graph is:\n\nI currently have the commit message below for my patch plus your fixup.\n\nThanks,\nMartin\n\n rev-list-options.txt: start a list for `show-pulls`\n\n The explanation of the `--show-pulls` option added in commit 8d049e182e\n (\"revision: --show-pulls adds helpful merges\", 2020-04-10) consists of\n several paragraphs and we use \"+\" throughout to tie them together in one\n long chain of list continuations. Only thing is, we're not in any kind\n of list, so these pluses end up being rendered literally.\n\n The preceding few paragraphs describe `--ancestry-path` and there we\n *do* have a list, since we've started one with `--ancestry-path::`. In\n fact, we have several such lists for all the various history-simplifying\n options we're discussing earlier in this file.\n\n Thus, we're missing a list both from a consistency point of view and\n from a practical rendering standpoint.\n\n Let's start a list for `--show-pulls` where we start actually discussing\n the option, and keep the paragraphs preceding it out of that list. That\n is, drop all those pluses before the new list we're adding here.\n\n Helped-by: Derrick Stolee \n Signed-off-by: Martin Ågren \n"},{"id":"398143","messageId":"xmqqsgfx0z9k.fsf@gitster.c.googlers.com","threadId":"53490","inReplyTo":"CAN0heSo_Y2Esp8X_amPXKaGaOVbP5rnJAyXiuUuW5BFSmwzhwA@mail.gmail.com","subject":"Re: [PATCH 7/7] rev-list-options.txt","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-05-18T20:22:15Z","receivedAt":"2020-05-18T20:22:20Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Martin Ågren writes:\n\n> I currently have the commit message below for my patch plus your fixup.\n> ...\n\nI've queued 1, 3, 4, 5, and 6 in the meantime. Todd gave us a\nreplacement for 2, which I also took.\n\nThanks.\n"},{"id":"398162","messageId":"20200518230646.GA20332@Carlos-MBP","threadId":"53490","inReplyTo":"e60236e18f73dcabce1a20ec17aee57fd54b11c9.1589739920.git.martin.agren@gmail.com","subject":"Re: [PATCH 5/7] git-credential.txt: use list continuation","fromName":"Carlo Marcelo Arenas Belón","fromEmail":"carenas@gmail.com","sentAt":"2020-05-18T23:06:46Z","receivedAt":"2020-05-18T23:06:51Z","isPatch":true,"sender":{"key":"carenas@gmail.com","avatar":"https://avatars.githubusercontent.com/u/76036?v=4"},"body":"Reviewed-by: Carlo Marcelo Arenas Belón \n\nThanks,\n\nCarlo\n"},{"id":"398495","messageId":"20200525170607.8000-1-martin.agren@gmail.com","threadId":"53490","inReplyTo":"xmqqsgfx0z9k.fsf@gitster.c.googlers.com","subject":"[PATCH v2] rev-list-options.txt: start a list for `show-pulls`","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2020-05-25T17:06:07Z","receivedAt":"2020-05-25T17:06:45Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On Mon, 18 May 2020 at 22:22, Junio C Hamano wrote:\n>\n> Martin Ågren writes:\n>\n> > I currently have the commit message below for my patch plus your fixup.\n> > ...\n>\n> I've queued 1, 3, 4, 5, and 6 in the meantime. Todd gave us a\n> replacement for 2, which I also took.\n>\n> Thanks.\n\nA long weekend offline passes and it's already a week later...\n\nHere is my original patch 7/7 plus Stolee's fixup, with the rephrased\ncommit message from upthread. I've tried to test it from all angles I\ncan think of -- AsciiDoc/Asciidoctor, man/html, doc-diff, ... It should\nbe low-risk and does avoid beginning ~20 paragraphs with a literal \"+\"\nin the rendered docs for this new option.\n\nMartin\n\n-- >8 --\nThe explanation of the `--show-pulls` option added in commit 8d049e182e\n(\"revision: --show-pulls adds helpful merges\", 2020-04-10) consists of\nseveral paragraphs and we use \"+\" throughout to tie them together in one\nlong chain of list continuations. Only thing is, we're not in any kind\nof list, so these pluses end up being rendered literally.\n\nThe preceding few paragraphs describe `--ancestry-path` and there we\n*do* have a list, since we've started one with `--ancestry-path::`. In\nfact, we have several such lists for all the various history-simplifying\noptions we're discussing earlier in this file.\n\nThus, we're missing a list both from a consistency point of view and\nfrom a practical rendering standpoint.\n\nLet's start a list for `--show-pulls` where we start actually discussing\nthe option, and keep the paragraphs preceding it out of that list. That\nis, drop all those pluses before the new list we're adding here.\n\nHelped-by: Derrick Stolee \nSigned-off-by: Martin Ågren \n---\n Documentation/rev-list-options.txt | 35 ++++++++++++++++--------------\n 1 file changed, 19 insertions(+), 16 deletions(-)\n\ndiff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt\nindex 04ad7dd36e..b01b2b6773 100644\n--- a/Documentation/rev-list-options.txt\n+++ b/Documentation/rev-list-options.txt\n@@ -581,12 +581,12 @@ option does. Applied to the 'D..M' range, it results in:\n \n Before discussing another option, `--show-pulls`, we need to\n create a new example history.\n-+\n+\n A common problem users face when looking at simplified history is that a\n commit they know changed a file somehow does not appear in the file's\n simplified history. Let's demonstrate a new example and show how options\n such as `--full-history` and `--simplify-merges` works in that case:\n-+\n+\n -----------------------------------------------------------------------\n \t .-A---M-----C--N---O---P\n \t / / \\ \\ \\/ / /\n@@ -595,7 +595,7 @@ such as `--full-history` and `--simplify-merges` works in that case:\n \t \\ / /\\ /\n \t `---X--' `---Y--'\n -----------------------------------------------------------------------\n-+\n+\n For this example, suppose `I` created `file.txt` which was modified by\n `A`, `B`, and `X` in different ways. The single-parent commits `C`, `Z`,\n and `Y` do not change `file.txt`. The merge commit `M` was created by\n@@ -607,19 +607,19 @@ the contents of `file.txt` at `X`. Hence, `R` is TREESAME to `X` but not\n contents of `file.txt` at `R`, so `N` is TREESAME to `R` but not `C`.\n The merge commits `O` and `P` are TREESAME to their first parents, but\n not to their second parents, `Z` and `Y` respectively.\n-+\n+\n When using the default mode, `N` and `R` both have a TREESAME parent, so\n those edges are walked and the others are ignored. The resulting history\n graph is:\n-+\n+\n -----------------------------------------------------------------------\n \tI---X\n -----------------------------------------------------------------------\n-+\n+\n When using `--full-history`, Git walks every edge. This will discover\n the commits `A` and `B` and the merge `M`, but also will reveal the\n merge commits `O` and `P`. With parent rewriting, the resulting graph is:\n-+\n+\n -----------------------------------------------------------------------\n \t .-A---M--------N---O---P\n \t / / \\ \\ \\/ / /\n@@ -628,21 +628,21 @@ merge commits `O` and `P`. With parent rewriting, the resulting graph is:\n \t \\ / /\\ /\n \t `---X--' `------'\n -----------------------------------------------------------------------\n-+\n+\n Here, the merge commits `O` and `P` contribute extra noise, as they did\n not actually contribute a change to `file.txt`. They only merged a topic\n that was based on an older version of `file.txt`. This is a common\n issue in repositories using a workflow where many contributors work in\n parallel and merge their topic branches along a single trunk: manu\n unrelated merges appear in the `--full-history` results.\n-+\n+\n When using the `--simplify-merges` option, the commits `O` and `P`\n disappear from the results. This is because the rewritten second parents\n of `O` and `P` are reachable from their first parents. Those edges are\n removed and then the commits look like single-parent commits that are\n TREESAME to their parent. This also happens to the commit `N`, resulting\n in a history view as follows:\n-+\n+\n -----------------------------------------------------------------------\n \t .-A---M--.\n \t / / \\\n@@ -651,18 +651,18 @@ in a history view as follows:\n \t \\ / /\n \t `---X--'\n -----------------------------------------------------------------------\n-+\n+\n In this view, we see all of the important single-parent changes from\n `A`, `B`, and `X`. We also see the carefully-resolved merge `M` and the\n not-so-carefully-resolved merge `R`. This is usually enough information\n to determine why the commits `A` and `B` \"disappeared\" from history in\n the default view. However, there are a few issues with this approach.\n-+\n+\n The first issue is performance. Unlike any previous option, the\n `--simplify-merges` option requires walking the entire commit history\n before returning a single result. This can make the option difficult to\n use for very large repositories.\n-+\n+\n The second issue is one of auditing. When many contributors are working\n on the same repository, it is important which merge commits introduced\n a change into an important branch. The problematic merge `R` above is\n@@ -671,10 +671,13 @@ important branch. Instead, the merge `N` was used to merge `R` and `X`\n into the important branch. This commit may have information about why\n the change `X` came to override the changes from `A` and `B` in its\n commit message.\n+\n+--show-pulls::\n+\tIn addition to the commits shown in the default history, show\n+\teach merge commit that is not TREESAME to its first parent but\n+\tis TREESAME to a later parent.\n +\n-The `--show-pulls` option helps with both of these issues by adding more\n-merge commits to the history results. If a merge is not TREESAME to its\n-first parent but is TREESAME to a later parent, then that merge is\n+When a merge commit is included by `--show-pulls`, the merge is\n treated as if it \"pulled\" the change from another branch. When using\n `--show-pulls` on this example (and no other options) the resulting\n graph is:\n-- \n2.27.0.rc0\n\n"},{"id":"398576","messageId":"4a3797f8-5169-b016-b1c4-ce544f00b34b@gmail.com","threadId":"53490","inReplyTo":"20200525170607.8000-1-martin.agren@gmail.com","subject":"Re: [PATCH v2] rev-list-options.txt: start a list for `show-pulls`","fromName":"Derrick Stolee","fromEmail":"stolee@gmail.com","sentAt":"2020-05-26T12:24:04Z","receivedAt":"2020-05-26T12:24:08Z","isPatch":true,"sender":{"key":"stolee@gmail.com","avatar":"https://avatars.githubusercontent.com/u/570044?v=4"},"body":"On 5/25/2020 1:06 PM, Martin Ågren wrote:\n> On Mon, 18 May 2020 at 22:22, Junio C Hamano wrote:\n> @@ -671,10 +671,13 @@ important branch. Instead, the merge `N` was used to merge `R` and `X`\n> into the important branch. This commit may have information about why\n> the change `X` came to override the changes from `A` and `B` in its\n> commit message.\n> +\n> +--show-pulls::\n> +\tIn addition to the commits shown in the default history, show\n> +\teach merge commit that is not TREESAME to its first parent but\n> +\tis TREESAME to a later parent.\n> +\n> -The `--show-pulls` option helps with both of these issues by adding more\n\nI like how you found a way to add the list item without needing to make a\nhuge shift in the surrounding prose. LGTM.\n\nThanks,\n-Stolee\n"},{"id":"398578","messageId":"xmqqv9kiohfv.fsf@gitster.c.googlers.com","threadId":"53490","inReplyTo":"20200525170607.8000-1-martin.agren@gmail.com","subject":"Re: [PATCH v2] rev-list-options.txt: start a list for `show-pulls`","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-05-26T15:16:04Z","receivedAt":"2020-05-26T15:16:12Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Martin Ågren writes:\n\n> Let's start a list for `--show-pulls` where we start actually discussing\n> the option, and keep the paragraphs preceding it out of that list. That\n> is, drop all those pluses before the new list we're adding here.\n\nThe way the \"History Simplification\" section is organized is\nsomewhat peculiar in that it begins with a short list of what's\navailable, followed by mixture of detailed explanation in prose. I\nagree with you two that the result of this patch fits very well to\nthe surrounding text.\n\nThis is not a new issue introduced by this patch, but ...\n\n> +--show-pulls::\n> +\tIn addition to the commits shown in the default history, show\n> +\teach merge commit that is not TREESAME to its first parent but\n> +\tis TREESAME to a later parent.\n> +\n> +When a merge commit is included by `--show-pulls`, the merge is\n> treated as if it \"pulled\" the change from another branch. When using\n> `--show-pulls` on this example (and no other options) the resulting\n> graph is:\n\n... \"is treated AS IF\" somewhat made me go \"huh?\"; with or without\nthe option, the merge did pull the change from another branch,\ndidn't it? The only effect the option has is to make that fact\nstand out in the output.\n\nBut rewording it is another topic totally different from \"we should\nrender this section correctly\" fix we have here, and should be done\n(if it needs to be done in the first place) separately after this\nchange lands.\n\nThanks, both.\n"},{"id":"398586","messageId":"474bbf51-bd40-837a-77de-1688f6488ae3@gmail.com","threadId":"53490","inReplyTo":"xmqqv9kiohfv.fsf@gitster.c.googlers.com","subject":"Re: [PATCH v2] rev-list-options.txt: start a list for `show-pulls`","fromName":"Derrick Stolee","fromEmail":"stolee@gmail.com","sentAt":"2020-05-26T17:01:40Z","receivedAt":"2020-05-26T17:01:43Z","isPatch":true,"sender":{"key":"stolee@gmail.com","avatar":"https://avatars.githubusercontent.com/u/570044?v=4"},"body":"On 5/26/2020 11:16 AM, Junio C Hamano wrote:\n> Martin Ågren writes:\n> \n>> Let's start a list for `--show-pulls` where we start actually discussing\n>> the option, and keep the paragraphs preceding it out of that list. That\n>> is, drop all those pluses before the new list we're adding here.\n> \n> The way the \"History Simplification\" section is organized is\n> somewhat peculiar in that it begins with a short list of what's\n> available, followed by mixture of detailed explanation in prose. I\n> agree with you two that the result of this patch fits very well to\n> the surrounding text.\n> \n> This is not a new issue introduced by this patch, but ...\n> \n>> +--show-pulls::\n>> +\tIn addition to the commits shown in the default history, show\n>> +\teach merge commit that is not TREESAME to its first parent but\n>> +\tis TREESAME to a later parent.\n>> +\n>> +When a merge commit is included by `--show-pulls`, the merge is\n>> treated as if it \"pulled\" the change from another branch. When using\n>> `--show-pulls` on this example (and no other options) the resulting\n>> graph is:\n> \n> ... \"is treated AS IF\" somewhat made me go \"huh?\"; with or without\n> the option, the merge did pull the change from another branch,\n> didn't it? The only effect the option has is to make that fact\n> stand out in the output.\n\nI guess the 'as if it \"pulled\" the change from another branch' sentence\nis literally talking about the \"git pull\" command, as opposed to the\n\"git merge\" command, or creating the merge upon completion of a pull request\non a Git service (which is almost always using libgit2 to generate a merge\ncommit).\n\nPerhaps there is no semantic difference between \"pulling\" and \"merging\"\nand then this could be reworded to be less awkward.\n\nThanks,\n-Stolee\n"},{"id":"398598","messageId":"CAN0heSq3mv8OcFiESVhN_fZ=iChSAUQ_Js0g=bTsY5dMepkk9A@mail.gmail.com","threadId":"53490","inReplyTo":"4a3797f8-5169-b016-b1c4-ce544f00b34b@gmail.com","subject":"Re: [PATCH v2] rev-list-options.txt: start a list for `show-pulls`","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2020-05-26T19:18:55Z","receivedAt":"2020-05-26T19:19:18Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"Hi Stolee,\n\nOn Tue, 26 May 2020 at 14:24, Derrick Stolee wrote:\n>\n> On 5/25/2020 1:06 PM, Martin Ågren wrote:\n> > On Mon, 18 May 2020 at 22:22, Junio C Hamano wrote:\n> > @@ -671,10 +671,13 @@ important branch. Instead, the merge `N` was used to merge `R` and `X`\n> > into the important branch. This commit may have information about why\n> > the change `X` came to override the changes from `A` and `B` in its\n> > commit message.\n> > +\n> > +--show-pulls::\n> > + In addition to the commits shown in the default history, show\n> > + each merge commit that is not TREESAME to its first parent but\n> > + is TREESAME to a later parent.\n> > +\n> > -The `--show-pulls` option helps with both of these issues by adding more\n>\n> I like how you found a way to add the list item without needing to make a\n> huge shift in the surrounding prose. LGTM.\n\nActually, I didn't see how to do it, but luckily, you did. [1] So I take\nthis to mean that even on re-reading your proposed text some time later,\nyou like it. ;-)\n\nMartin\n\n[1] https://lore.kernel.org/git/34870e5f-8e61-4af8-1050-43bfbe30d8f9@gmail.com/\n"},{"id":"398599","messageId":"CAN0heSp-D8qfKzDfBYxLA-76v=E_VgKWtfitCFb8DdWiHqMDmw@mail.gmail.com","threadId":"53490","inReplyTo":"474bbf51-bd40-837a-77de-1688f6488ae3@gmail.com","subject":"Re: [PATCH v2] rev-list-options.txt: start a list for `show-pulls`","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2020-05-26T19:20:19Z","receivedAt":"2020-05-26T19:20:35Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On Tue, 26 May 2020 at 19:01, Derrick Stolee wrote:\n>\n> On 5/26/2020 11:16 AM, Junio C Hamano wrote:\n> > Martin Ågren writes:\n> >\n> > This is not a new issue introduced by this patch, but ...\n> >\n> >> +--show-pulls::\n> >> + In addition to the commits shown in the default history, show\n> >> + each merge commit that is not TREESAME to its first parent but\n> >> + is TREESAME to a later parent.\n> >> +\n> >> +When a merge commit is included by `--show-pulls`, the merge is\n> >> treated as if it \"pulled\" the change from another branch. When using\n> >> `--show-pulls` on this example (and no other options) the resulting\n> >> graph is:\n> >\n> > ... \"is treated AS IF\" somewhat made me go \"huh?\"; with or without\n> > the option, the merge did pull the change from another branch,\n> > didn't it? The only effect the option has is to make that fact\n> > stand out in the output.\n>\n> I guess the 'as if it \"pulled\" the change from another branch' sentence\n> is literally talking about the \"git pull\" command, as opposed to the\n> \"git merge\" command, or creating the merge upon completion of a pull request\n> on a Git service (which is almost always using libgit2 to generate a merge\n> commit).\n>\n> Perhaps there is no semantic difference between \"pulling\" and \"merging\"\n> and then this could be reworded to be less awkward.\n\nAgreed on the awkwardness as it stands (before or after this proposed\npatch). I don't have any concrete thoughts to offer though.\n\nMartin\n"}]}