{"thread":{"id":"64591","subject":"[PATCH 0/3] doc: replay: improvements like \"mention no output on conflicts\"","startedAt":"2025-12-07T17:55:39Z","lastAt":"2025-12-20T19:34:59Z","messageCount":28,"participants":["kristofferhaugsbakk@fastmail.com","Junio C Hamano","Kristoffer Haugsbakk","Toon Claes","Phillip Wood","Elijah Newren"],"isPatch":true,"patchVersion":1,"patchTotal":3},"messages":[{"id":"531797","messageId":"CV_replay_conflict.101@msgid.xyz","threadId":"64591","inReplyTo":null,"subject":"[PATCH 0/3] doc: replay: improvements like \"mention no output on conflicts\"","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-12-07T17:55:08Z","receivedAt":"2025-12-07T17:55:39Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"From: Kristoffer Haugsbakk \n\nExplicitly say that conflicts do not give any output. I found this a bit\nconfusing with the current doc since I am used to other commands\ncomplaining loudly.\n\nAlso two other things:\n\nKristoffer Haugsbakk (3):\n doc: replay: mention no output on conflicts\n doc: replay: document --contained\n doc: replay: link section using markup\n\n Documentation/git-replay.adoc | 10 +++++++++-\n 1 file changed, 9 insertions(+), 1 deletion(-)\n\n\nbase-commit: bdc5341ff65278a3cc80b2e8a02a2f02aa1fac06\n-- \n2.52.0.10.g08704017180\n\n"},{"id":"531798","messageId":"no_output_on_conflict.102@msgid.xyz","threadId":"64591","inReplyTo":"CV_replay_conflict.101@msgid.xyz","subject":"[PATCH 1/3] doc: replay: mention no output on conflicts","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-12-07T17:55:09Z","receivedAt":"2025-12-07T17:55:58Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"From: Kristoffer Haugsbakk \n\nSome commands will produce output on stderr if there are conflicts, but\ngit-replay(1) is completely silent. Explicitly spell that out.\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n Documentation/git-replay.adoc | 4 ++++\n 1 file changed, 4 insertions(+)\n\ndiff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc\nindex dcb26e8a8e8..6fbb527b9d8 100644\n--- a/Documentation/git-replay.adoc\n+++ b/Documentation/git-replay.adoc\n@@ -81,6 +81,10 @@ the shape of the history being replayed. When using `--advance`, the\n number of refs updated is always one, but for `--onto`, it can be one\n or more (rebasing multiple branches simultaneously is supported).\n \n+There is no stderr output on conflicts; see the <> section below.\n+\n+[[exit-status]]\n EXIT STATUS\n -----------\n \n-- \n2.52.0.10.g08704017180\n\n"},{"id":"531799","messageId":"doc_replay_--contained.103@msgid.xyz","threadId":"64591","inReplyTo":"CV_replay_conflict.101@msgid.xyz","subject":"[PATCH 2/3] doc: replay: document --contained","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-12-07T17:55:10Z","receivedAt":"2025-12-07T17:56:17Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"From: Kristoffer Haugsbakk \n\nCopy the text from `replay_options` in `builtin/replay.c`.\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n Documentation/git-replay.adoc | 3 +++\n 1 file changed, 3 insertions(+)\n\ndiff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc\nindex 6fbb527b9d8..1b8661185bb 100644\n--- a/Documentation/git-replay.adoc\n+++ b/Documentation/git-replay.adoc\n@@ -42,6 +42,9 @@ The history is replayed on top of the and is updated to\n point at the tip of the resulting history. This is different from `--onto`,\n which uses the target only as a starting point without updating it.\n \n+--contained::\n+\tAdvance all branches contained in .\n+\n --ref-action[=]::\n \tControl how references are updated. The mode can be:\n +\n-- \n2.52.0.10.g08704017180\n\n"},{"id":"531800","messageId":"link_OUTPUT_section.104@msgid.xyz","threadId":"64591","inReplyTo":"CV_replay_conflict.101@msgid.xyz","subject":"[PATCH 3/3] doc: replay: link section using markup","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-12-07T17:55:11Z","receivedAt":"2025-12-07T17:56:35Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"From: Kristoffer Haugsbakk \n\nSigned-off-by: Kristoffer Haugsbakk \n---\n Documentation/git-replay.adoc | 3 ++-\n 1 file changed, 2 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc\nindex 1b8661185bb..04944a5fa23 100644\n--- a/Documentation/git-replay.adoc\n+++ b/Documentation/git-replay.adoc\n@@ -19,7 +19,7 @@ the working tree and the index untouched. By default, updates the\n relevant references using an atomic transaction (all refs update or\n none). Use `--ref-action=print` to avoid automatic ref updates and\n instead get update commands that can be piped to `git update-ref --stdin`\n-(see the OUTPUT section below).\n+(see the <> section below).\n \n THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE.\n \n@@ -66,6 +66,7 @@ The default mode can be configured via the `replay.refAction` configuration vari\n \n include::rev-list-options.adoc[]\n \n+[[output]]\n OUTPUT\n ------\n \n-- \n2.52.0.10.g08704017180\n\n"},{"id":"531803","messageId":"xmqq1pl6lzt6.fsf@gitster.g","threadId":"64591","inReplyTo":"CV_replay_conflict.101@msgid.xyz","subject":"Re: [PATCH 0/3] doc: replay: improvements like \"mention no output on conflicts\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-12-07T21:58:13Z","receivedAt":"2025-12-07T21:58:16Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"kristofferhaugsbakk@fastmail.com writes:\n\n> From: Kristoffer Haugsbakk \n>\n> Explicitly say that conflicts do not give any output. I found this a bit\n> confusing with the current doc since I am used to other commands\n> complaining loudly.\n>\n> Also two other things:\n>\n> Kristoffer Haugsbakk (3):\n> doc: replay: mention no output on conflicts\n> doc: replay: document --contained\n> doc: replay: link section using markup\n>\n> Documentation/git-replay.adoc | 10 +++++++++-\n> 1 file changed, 9 insertions(+), 1 deletion(-)\n>\n>\n> base-commit: bdc5341ff65278a3cc80b2e8a02a2f02aa1fac06\n\nAll looked sensible.\n\nThe second one looked a bit sketchy, but that was the phrase used by\nthe log message for c4611130 (replay: add --contained to rebase\ncontained branches, 2023-11-24).\n"},{"id":"531812","messageId":"d2a72ba5-ac7c-490f-9f2c-6cf849e65180@app.fastmail.com","threadId":"64591","inReplyTo":"xmqq1pl6lzt6.fsf@gitster.g","subject":"Re: [PATCH 0/3] doc: replay: improvements like \"mention no output on conflicts\"","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-12-08T07:28:52Z","receivedAt":"2025-12-08T07:29:14Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"On Sun, Dec 7, 2025, at 22:58, Junio C Hamano wrote:\n> kristofferhaugsbakk@fastmail.com writes:\n>>[snip]\n>> base-commit: bdc5341ff65278a3cc80b2e8a02a2f02aa1fac06\n>\n> All looked sensible.\n>\n> The second one looked a bit sketchy, but that was the phrase used by\n> the log message for c4611130 (replay: add --contained to rebase\n> contained branches, 2023-11-24).\n\nHow should `--contained` be documented?\n"},{"id":"531830","messageId":"xmqqms3tkux8.fsf@gitster.g","threadId":"64591","inReplyTo":"d2a72ba5-ac7c-490f-9f2c-6cf849e65180@app.fastmail.com","subject":"Re: [PATCH 0/3] doc: replay: improvements like \"mention no output on conflicts\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-12-08T12:41:23Z","receivedAt":"2025-12-08T12:41:26Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Kristoffer Haugsbakk\" writes:\n\n> On Sun, Dec 7, 2025, at 22:58, Junio C Hamano wrote:\n>> kristofferhaugsbakk@fastmail.com writes:\n>>>[snip]\n>>> base-commit: bdc5341ff65278a3cc80b2e8a02a2f02aa1fac06\n>>\n>> All looked sensible.\n>>\n>> The second one looked a bit sketchy, but that was the phrase used by\n>> the log message for c4611130 (replay: add --contained to rebase\n>> contained branches, 2023-11-24).\n>\n> How should `--contained` be documented?\n\nThe text you added uses exactly the phrase used by the log message,\nso the author of the feature apparently felt it is good enough ;-).\n\nIt just felt that \"contained in \" is understandable\nenough. For example, I am unsure if somebody who read the document\ncan accurately answer the following question:\n\n If you forked 7-commit series from v1.0, merged the early 3\n commits to the 'master' branch, and merged the rest to the\n 'next' branch, is that branch contained in 'master..next'? Or\n it is not because the bottommost 3 commits are not part of\n master..next? If it is the former, is it because the topmost\n commit (i.e., the commit pointed at by the branch reference) is\n the only thing that counts, and it indeed is master..next?\n\n"},{"id":"531833","messageId":"877buxvygi.fsf@iotcl.com","threadId":"64591","inReplyTo":"d2a72ba5-ac7c-490f-9f2c-6cf849e65180@app.fastmail.com","subject":"Re: [PATCH 0/3] doc: replay: improvements like \"mention no output on conflicts\"","fromName":"Toon Claes","fromEmail":"toon@iotcl.com","sentAt":"2025-12-08T14:29:33Z","receivedAt":"2025-12-08T14:29:53Z","isPatch":true,"sender":{"key":"toon@iotcl.com","avatar":"https://avatars.githubusercontent.com/u/121621?v=4"},"body":"\"Kristoffer Haugsbakk\" writes:\n\n>>> Explicitly say that conflicts do not give any output. I found this a\n>>> bit confusing with the current doc since I am used to other commands\n>>> complaining loudly.\n\nYeah I agree it's unusual, and I'm considering to submit patches to\nchange that behavior. But for now, thanks for adding these docs changes.\n\n> On Sun, Dec 7, 2025, at 22:58, Junio C Hamano wrote:\n>>\n>> All looked sensible.\n>>\n>> The second one looked a bit sketchy, but that was the phrase used by\n>> the log message for c4611130 (replay: add --contained to rebase\n>> contained branches, 2023-11-24).\n>\n> How should `--contained` be documented?\n\nI understand it might sound a bit cryptic, if you don't have any prior\nknowledge about this command. But on the other hand, I don't have any\ngood idea how you can document this in more detail. I think it's fine\nlike this.\n\nOverall, I agree with these changes.\n\n-- \nCheers,\nToon\n"},{"id":"531835","messageId":"d848e8fe-7ecc-4197-ac27-d87509f2039c@app.fastmail.com","threadId":"64591","inReplyTo":"877buxvygi.fsf@iotcl.com","subject":"Re: [PATCH 0/3] doc: replay: improvements like \"mention no output on conflicts\"","fromName":"Kristoffer Haugsbakk","fromEmail":"code@khaugsbakk.name","sentAt":"2025-12-08T14:35:59Z","receivedAt":"2025-12-08T14:36:20Z","isPatch":true,"sender":{"key":"code@khaugsbakk.name","avatar":"https://avatars.githubusercontent.com/u/2229597?v=4"},"body":"On Mon, Dec 8, 2025, at 15:29, Toon Claes wrote:\n> \"Kristoffer Haugsbakk\" writes:\n>\n>>>> Explicitly say that conflicts do not give any output. I found this a\n>>>> bit confusing with the current doc since I am used to other commands\n>>>> complaining loudly.\n>\n> Yeah I agree it's unusual, and I'm considering to submit patches to\n> change that behavior. But for now, thanks for adding these docs changes.\n\nThanks for reviewing/checking this out!\n\n>> On Sun, Dec 7, 2025, at 22:58, Junio C Hamano wrote:\n>>>\n>>> All looked sensible.\n>>>\n>>> The second one looked a bit sketchy, but that was the phrase used by\n>>> the log message for c4611130 (replay: add --contained to rebase\n>>> contained branches, 2023-11-24).\n>>\n>> How should `--contained` be documented?\n>\n> I understand it might sound a bit cryptic, if you don't have any prior\n> knowledge about this command. But on the other hand, I don't have any\n> good idea how you can document this in more detail. I think it's fine\n> like this.\n\nIt sounds like it is the same as `git rebase --update-refs`. I guess\nthat could be mentioned?\n\n>\n> Overall, I agree with these changes.\n"},{"id":"531838","messageId":"7d0201aa-905c-4da2-932d-47666c923875@gmail.com","threadId":"64591","inReplyTo":"d2a72ba5-ac7c-490f-9f2c-6cf849e65180@app.fastmail.com","subject":"Re: [PATCH 0/3] doc: replay: improvements like \"mention no output on conflicts\"","fromName":"Phillip Wood","fromEmail":"phillip.wood123@gmail.com","sentAt":"2025-12-08T16:00:16Z","receivedAt":"2025-12-08T16:00:20Z","isPatch":true,"sender":{"key":"phillip.wood@dunelm.org.uk","avatar":null},"body":"On 08/12/2025 07:28, Kristoffer Haugsbakk wrote:\n> On Sun, Dec 7, 2025, at 22:58, Junio C Hamano wrote:\n>> kristofferhaugsbakk@fastmail.com writes:\n>>> [snip]\n>>> base-commit: bdc5341ff65278a3cc80b2e8a02a2f02aa1fac06\n>>\n>> All looked sensible.\n>>\n>> The second one looked a bit sketchy, but that was the phrase used by\n>> the log message for c4611130 (replay: add --contained to rebase\n>> contained branches, 2023-11-24).\n> \n> How should `--contained` be documented?\n\nMaybe something like\n\n Update all branches whose head commits are replayed. Requires\n --onto.\n\nThanks\n\nPhillip\n\n"},{"id":"531904","messageId":"202f7015-1e7f-493e-bd82-474e5cefdf01@app.fastmail.com","threadId":"64591","inReplyTo":"7d0201aa-905c-4da2-932d-47666c923875@gmail.com","subject":"Re: [PATCH 0/3] doc: replay: improvements like \"mention no output on conflicts\"","fromName":"Kristoffer Haugsbakk","fromEmail":"code@khaugsbakk.name","sentAt":"2025-12-09T18:03:51Z","receivedAt":"2025-12-09T18:04:15Z","isPatch":true,"sender":{"key":"code@khaugsbakk.name","avatar":"https://avatars.githubusercontent.com/u/2229597?v=4"},"body":"On Mon, Dec 8, 2025, at 17:00, Phillip Wood wrote:\n> On 08/12/2025 07:28, Kristoffer Haugsbakk wrote:\n>> On Sun, Dec 7, 2025, at 22:58, Junio C Hamano wrote:\n>>> kristofferhaugsbakk@fastmail.com writes:\n>>>> [snip]\n>>>\n>>> The second one looked a bit sketchy, but that was the phrase used by\n>>> the log message for c4611130 (replay: add --contained to rebase\n>>> contained branches, 2023-11-24).\n>>\n>> How should `--contained` be documented?\n>\n> Maybe something like\n>\n> Update all branches whose head commits are replayed. Requires\n> --onto.\n\nThanks for the suggestion, and nice catch with the `--onto`. Very\npersonally I don’t like involving “head” terminology. Both because of\npersonal biases[1] as well as introducing “head” as a noun in the doc\n(now it just talks about `refs/heads/`).\n\nI will discuss the current phrasing “Advance all branches contained in\n” in my next email.\n\n† 1: I like the school-of-terminology that says that branches are just a\n particular ref namespace that point to a commit; a branch points to a\n commit, that’s it, that’s all a branch is. Contrast with the\n “branch” gitglossary(7) which says that\n\n A \"branch\" is a line of development. The most recent commit on\n a branch is referred to as the tip of that branch. ...\n\n This is both more involved and causes pedagogical headaches as\n people start wrestling with where a branch “begins” (it is a “line\n of development” after all) in the face of inevitable moves of the\n branch where it started (but the “branch where it started” is of\n course immaterial; it’s the commit that that other branch pointed\n at *at* the time that matters ...) ...\n"},{"id":"531905","messageId":"753daaa4-e675-4d28-9c13-4f5ede0f3b47@app.fastmail.com","threadId":"64591","inReplyTo":"xmqqms3tkux8.fsf@gitster.g","subject":"Re: [PATCH 0/3] doc: replay: improvements like \"mention no output on conflicts\"","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-12-09T18:05:02Z","receivedAt":"2025-12-09T18:05:32Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"On Mon, Dec 8, 2025, at 13:41, Junio C Hamano wrote:\n>>>[snip]\n>>>\n>>> All looked sensible.\n>>>\n>>> The second one looked a bit sketchy, but that was the phrase used by\n>>> the log message for c4611130 (replay: add --contained to rebase\n>>> contained branches, 2023-11-24).\n>>\n>> How should `--contained` be documented?\n>\n> The text you added uses exactly the phrase used by the log message,\n> so the author of the feature apparently felt it is good enough ;-).\n>\n> It just felt that \"contained in \" is understandable\n> enough.\n\n“is [not]” presumably.\n\nI read it as this with pseudo-decoration.\n\n abcde (refs/heads/topic2)\n 12345\n 56789 (refs/heads/topic1)\n 0abcd\n\n`topic1` and `topic2` are contained and will be updated.\n\n> For example, I am unsure if somebody who read the document can\n> accurately answer the following question:\n>\n> If you forked 7-commit series from v1.0, merged the early 3\n> commits to the 'master' branch, and merged the rest to the\n> 'next' branch, is that branch contained in 'master..next'?\n\nI tested that with, let’s say, `topic-1` merged to a `test-master` (and\n`topic-2` merged to a `test-next).\n\n`git log test-master..test-next` was as expected (no `topic-1`). Replaying onto\none commit on top of `test-next`:[1]\n\n $ git replay --contained --onto=test-target test-master..test-next\n \n\nI guess the “duplicates” (patch-id) cause this?\n\n> Or it is not because the bottommost 3 commits are not part of\n> master..next? If it is the former, is it because the topmost\n> commit (i.e., the commit pointed at by the branch reference) is\n> the only thing that counts, and it indeed is master..next?\n\nIt’s a somewhat complex case compared to what I think is the usual one:\na non-merge range of commits without any patch-id-equivalents on the\ntarget (fingers crossed). And the setup without merges: two topic\nbranches in the range gives the output I expect:\n\n git replay --contained --onto=target2 \n update \n update \n\nI think the original phrasing is understandable. But we could add\nan example.\n\n For example, if the range contains five commits where a branch\n points to the newest commit and another branch points to the third\n commit ...\n\nAnd should the description in the source (replay.c) be updated as well?\nThis goes for Phillip’s point about “Requires --onto” as well.\n\n† 1: By the way: me mistyping `--onto=` where `` doesn’t\n exist causes this error:\n\n fatal: Replaying down to root commit is not supported yet!\n"},{"id":"531925","messageId":"xmqqzf7ri7q7.fsf@gitster.g","threadId":"64591","inReplyTo":"202f7015-1e7f-493e-bd82-474e5cefdf01@app.fastmail.com","subject":"Re: [PATCH 0/3] doc: replay: improvements like \"mention no output on conflicts\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-12-09T22:57:36Z","receivedAt":"2025-12-09T22:57:40Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Kristoffer Haugsbakk\" writes:\n\n> On Mon, Dec 8, 2025, at 17:00, Phillip Wood wrote:\n> ...\n>> Maybe something like\n>>\n>> Update all branches whose head commits are replayed. Requires\n>> --onto.\n>\n> Thanks for the suggestion, and nice catch with the `--onto`. Very\n> personally I don’t like involving “head” terminology. Both because of\n> personal biases[1] as well as introducing “head” as a noun in the doc\n> (now it just talks about `refs/heads/`).\n\nYeah, I do not recall calling commit at the tip of a branch a \"head\ncommit\".\n"},{"id":"531933","messageId":"xmqqtsxzi7hx.fsf@gitster.g","threadId":"64591","inReplyTo":"753daaa4-e675-4d28-9c13-4f5ede0f3b47@app.fastmail.com","subject":"Re: [PATCH 0/3] doc: replay: improvements like \"mention no output on conflicts\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-12-09T23:02:34Z","receivedAt":"2025-12-09T23:02:37Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Kristoffer Haugsbakk\" writes:\n\n> On Mon, Dec 8, 2025, at 13:41, Junio C Hamano wrote:\n>>>>[snip]\n>>>>\n>>>> All looked sensible.\n>>>>\n>>>> The second one looked a bit sketchy, but that was the phrase used by\n>>>> the log message for c4611130 (replay: add --contained to rebase\n>>>> contained branches, 2023-11-24).\n>>>\n>>> How should `--contained` be documented?\n>>\n>> The text you added uses exactly the phrase used by the log message,\n>> so the author of the feature apparently felt it is good enough ;-).\n>>\n>> It just felt that \"contained in \" is understandable\n>> enough.\n>\n> “is [not]” presumably.\n\nActually, s/It felt/I was unsure/;-).\n\n>> master..next? If it is the former, is it because the topmost\n>> commit (i.e., the commit pointed at by the branch reference) is\n>> the only thing that counts, and it indeed is master..next?\n>\n> It’s a somewhat complex case compared to what I think is the usual one:\n> a non-merge range of commits without any patch-id-equivalents on the\n> target (fingers crossed). And the setup without merges: two topic\n> branches in the range gives the output I expect:\n>\n> git replay --contained --onto=target2 \n> update \n> update \n>\n> I think the original phrasing is understandable. But we could add\n> an example.\n>\n> For example, if the range contains five commits where a branch\n> points to the newest commit and another branch points to the third\n> commit ...\n\nAlternatively, you can explicitly refer to \"the tip of the branch\";\nthat phrasing will be understood by people from both camps. Those\nwho considers that a \"branch\" consists of the commits between the\nfork point and its tip, and those who thinks a \"branch\" is a fancy\nname attached to one particular commit in the DAG that can move\naround (typically forward). Those branches whose tips are within\nthe range are updated.\n"},{"id":"531953","messageId":"74a705b5-bafe-4304-86ea-fd3873ae4fb4@gmail.com","threadId":"64591","inReplyTo":"xmqqzf7ri7q7.fsf@gitster.g","subject":"Re: [PATCH 0/3] doc: replay: improvements like \"mention no output on conflicts\"","fromName":"Phillip Wood","fromEmail":"phillip.wood123@gmail.com","sentAt":"2025-12-10T09:51:21Z","receivedAt":"2025-12-10T09:51:28Z","isPatch":true,"sender":{"key":"phillip.wood@dunelm.org.uk","avatar":null},"body":"On 09/12/2025 22:57, Junio C Hamano wrote:\n> \"Kristoffer Haugsbakk\" writes:\n> \n>> On Mon, Dec 8, 2025, at 17:00, Phillip Wood wrote:\n>> ...\n>>> Maybe something like\n>>>\n>>> Update all branches whose head commits are replayed. Requires\n>>> --onto.\n>>\n>> Thanks for the suggestion, and nice catch with the `--onto`. Very\n>> personally I don’t like involving “head” terminology. Both because of\n>> personal biases[1] as well as introducing “head” as a noun in the doc\n>> (now it just talks about `refs/heads/`).\n> \n> Yeah, I do not recall calling commit at the tip of a branch a \"head\n> commit\".\n\nWe do talk about \"branch heads\" in our documentation and they point \ncommits. We also use \"tip\" when talking about the commit the branch \npoints to so maybe something like\n\n Update all branches whose tip is replayed\n\nthough I think it would be clearer if we could say \"commit\" somewhere as \nthat's what we're replaying. I find the concept of \"contained branches\" \nrather obscure.\n\nThanks\n\nPhillip\n\n"},{"id":"531962","messageId":"xmqq1pl2im8x.fsf@gitster.g","threadId":"64591","inReplyTo":"74a705b5-bafe-4304-86ea-fd3873ae4fb4@gmail.com","subject":"Re: [PATCH 0/3] doc: replay: improvements like \"mention no output on conflicts\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-12-10T11:56:14Z","receivedAt":"2025-12-10T11:56:18Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Phillip Wood writes:\n\n> We do talk about \"branch heads\" in our documentation and they point \n> commits. We also use \"tip\" when talking about the commit the branch \n> points to so maybe something like\n>\n> Update all branches whose tip is replayed\n>\n> though I think it would be clearer if we could say \"commit\" somewhere as \n> that's what we're replaying. I find the concept of \"contained branches\" \n> rather obscure.\n\nThanks, I do agree that \"branch head\", \"tip of the branch\", etc. can\nbe used pretty much interchangeably, and using \"commit\" somwhere\nwould make it clear.\n\n\tUpdate all branches that point at commits in the replayed\n\t.\n\nperhaps? I dunno.\n\n"},{"id":"531964","messageId":"85ce46a9-a097-462a-aa1b-904eeb7b89ad@app.fastmail.com","threadId":"64591","inReplyTo":"xmqq1pl2im8x.fsf@gitster.g","subject":"Re: [PATCH 0/3] doc: replay: improvements like \"mention no output on conflicts\"","fromName":"Kristoffer Haugsbakk","fromEmail":"code@khaugsbakk.name","sentAt":"2025-12-10T12:04:45Z","receivedAt":"2025-12-10T12:05:06Z","isPatch":true,"sender":{"key":"code@khaugsbakk.name","avatar":"https://avatars.githubusercontent.com/u/2229597?v=4"},"body":"On Wed, Dec 10, 2025, at 12:56, Junio C Hamano wrote:\n> Phillip Wood writes:\n>\n>> We do talk about \"branch heads\" in our documentation and they point \n>> commits. We also use \"tip\" when talking about the commit the branch \n>> points to so maybe something like\n>>\n>> Update all branches whose tip is replayed\n>>\n>> though I think it would be clearer if we could say \"commit\" somewhere as \n>> that's what we're replaying. I find the concept of \"contained branches\" \n>> rather obscure.\n>\n> Thanks, I do agree that \"branch head\", \"tip of the branch\", etc. can\n> be used pretty much interchangeably, and using \"commit\" somwhere\n> would make it clear.\n>\n> \tUpdate all branches that point at commits in the replayed\n> \t.\n>\n> perhaps? I dunno.\n\nI like this. Or just\n\n Update all branches that point at commits in .\n"},{"id":"531974","messageId":"12b0e7dc-4c00-4f0e-bef7-ff76f3054b71@gmail.com","threadId":"64591","inReplyTo":"85ce46a9-a097-462a-aa1b-904eeb7b89ad@app.fastmail.com","subject":"Re: [PATCH 0/3] doc: replay: improvements like \"mention no output on conflicts\"","fromName":"Phillip Wood","fromEmail":"phillip.wood123@gmail.com","sentAt":"2025-12-10T14:14:00Z","receivedAt":"2025-12-10T14:14:09Z","isPatch":true,"sender":{"key":"phillip.wood@dunelm.org.uk","avatar":null},"body":"On 10/12/2025 12:04, Kristoffer Haugsbakk wrote:\n> On Wed, Dec 10, 2025, at 12:56, Junio C Hamano wrote:\n>> Phillip Wood writes:\n>>\n>>> We do talk about \"branch heads\" in our documentation and they point\n>>> commits. We also use \"tip\" when talking about the commit the branch\n>>> points to so maybe something like\n>>>\n>>> Update all branches whose tip is replayed\n>>>\n>>> though I think it would be clearer if we could say \"commit\" somewhere as\n>>> that's what we're replaying. I find the concept of \"contained branches\"\n>>> rather obscure.\n>>\n>> Thanks, I do agree that \"branch head\", \"tip of the branch\", etc. can\n>> be used pretty much interchangeably, and using \"commit\" somwhere\n>> would make it clear.\n>>\n>> \tUpdate all branches that point at commits in the replayed\n>> \t.\n>>\n>> perhaps? I dunno.\n> \n> I like this. Or just\n> \n> Update all branches that point at commits in .\n\nI'd be happy with either one\n\nThanks\n\nPhillip\n\n"},{"id":"531992","messageId":"CABPp-BHk+Vm5PvBJ12T50kZsZM1DFOj5eZ7sAPu8j3sanF8SKw@mail.gmail.com","threadId":"64591","inReplyTo":"12b0e7dc-4c00-4f0e-bef7-ff76f3054b71@gmail.com","subject":"Re: [PATCH 0/3] doc: replay: improvements like \"mention no output on conflicts\"","fromName":"Elijah Newren","fromEmail":"newren@gmail.com","sentAt":"2025-12-10T15:40:06Z","receivedAt":"2025-12-10T15:40:18Z","isPatch":true,"sender":{"key":"newren@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5455730?v=4"},"body":"On Wed, Dec 10, 2025 at 6:14 AM Phillip Wood wrote:\n>\n> On 10/12/2025 12:04, Kristoffer Haugsbakk wrote:\n> > On Wed, Dec 10, 2025, at 12:56, Junio C Hamano wrote:\n> >> Phillip Wood writes:\n> >>\n> >>> We do talk about \"branch heads\" in our documentation and they point\n> >>> commits. We also use \"tip\" when talking about the commit the branch\n> >>> points to so maybe something like\n> >>>\n> >>> Update all branches whose tip is replayed\n> >>>\n> >>> though I think it would be clearer if we could say \"commit\" somewhere as\n> >>> that's what we're replaying. I find the concept of \"contained branches\"\n> >>> rather obscure.\n> >>\n> >> Thanks, I do agree that \"branch head\", \"tip of the branch\", etc. can\n> >> be used pretty much interchangeably, and using \"commit\" somwhere\n> >> would make it clear.\n> >>\n> >> Update all branches that point at commits in the replayed\n> >> .\n> >>\n> >> perhaps? I dunno.\n> >\n> > I like this. Or just\n> >\n> > Update all branches that point at commits in .\n>\n> I'd be happy with either one\n\nSame.\n"},{"id":"532130","messageId":"V2_CV_replay_conflict.12f@msgid.xyz","threadId":"64591","inReplyTo":"CV_replay_conflict.101@msgid.xyz","subject":"[PATCH v2 0/3] doc: replay: improvements like \"mention no output on conflicts\"","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-12-13T13:46:55Z","receivedAt":"2025-12-13T13:47:10Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"From: Kristoffer Haugsbakk \n\nExplicitly say that conflicts do not give any output. I found this a bit\nconfusing with the current doc since I am used to other commands\ncomplaining loudly.\n\n§ Changes in v2\n\nPatch 2/3: improve `--contained` and mention that it requires `--onto`.\n\nKristoffer Haugsbakk (3):\n doc: replay: mention no output on conflicts\n replay: improve --contained and add to doc\n doc: replay: link section using markup\n\n Documentation/git-replay.adoc | 11 ++++++++++-\n builtin/replay.c | 2 +-\n 2 files changed, 11 insertions(+), 2 deletions(-)\n\nInterdiff against v1:\ndiff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc\nindex 04944a5fa23..22fd1b271af 100644\n--- a/Documentation/git-replay.adoc\n+++ b/Documentation/git-replay.adoc\n@@ -43,7 +43,8 @@ point at the tip of the resulting history. This is different from `--onto`,\n which uses the target only as a starting point without updating it.\n \n --contained::\n-\tAdvance all branches contained in .\n+\tUpdate all branches that point at commits in\n+\t. Requires `--onto`.\n \n --ref-action[=]::\n \tControl how references are updated. The mode can be:\ndiff --git a/builtin/replay.c b/builtin/replay.c\nindex 6606a2c94bc..9e5ad64cad6 100644\n--- a/builtin/replay.c\n+++ b/builtin/replay.c\n@@ -377,7 +377,7 @@ int cmd_replay(int argc,\n \t\t\t N_(\"revision\"),\n \t\t\t N_(\"replay onto given commit\")),\n \t\tOPT_BOOL(0, \"contained\", &contained,\n-\t\t\t N_(\"advance all branches contained in revision-range\")),\n+\t\t\t N_(\"update all branches that point at commits in \")),\n \t\tOPT_STRING(0, \"ref-action\", &ref_action,\n \t\t\t N_(\"mode\"),\n \t\t\t N_(\"control ref update behavior (update|print)\")),\nRange-diff against v1:\n1: b9ec24c8b8f = 1: b9ec24c8b8f doc: replay: mention no output on conflicts\n2: 02a80ee87b5 ! 2: 27bf2ac7a0b doc: replay: document --contained\n @@ Metadata\n Author: Kristoffer Haugsbakk \n \n ## Commit message ##\n - doc: replay: document --contained\n + replay: improve --contained and add to doc\n \n - Copy the text from `replay_options` in `builtin/replay.c`.\n + There is no documentation for `--contained`.\n \n + Start by copying the text from `replay_options` in `builtin/\n + replay.c`. But some people think that the existing text is a\n + bit unclear; what does it mean for a branch to be contained\n + in a revision range? Let’s include the implied commits here:\n + the branches that point at commits in the range.\n +\n + Also use “update” instead of “advance”. “Update” is the verb\n + commonly used in this context.\n +\n + Helped-by: Phillip Wood \n + Helped-by: Junio C Hamano \n Signed-off-by: Kristoffer Haugsbakk \n \n +\n + ## Notes (series) ##\n + v2:\n +\n + Don’t just copy `--contained` over. Improve it on both sites after discussing\n + with reviewers.\n +\n + Also mention that `--onto` is required.\n +\n ## Documentation/git-replay.adoc ##\n @@ Documentation/git-replay.adoc: The history is replayed on top of the and is updated to\n point at the tip of the resulting history. This is different from `--onto`,\n which uses the target only as a starting point without updating it.\n \n +--contained::\n -+\tAdvance all branches contained in .\n ++\tUpdate all branches that point at commits in\n ++\t. Requires `--onto`.\n +\n --ref-action[=]::\n \tControl how references are updated. The mode can be:\n +\n +\n + ## builtin/replay.c ##\n +@@ builtin/replay.c: int cmd_replay(int argc,\n + \t\t\t N_(\"revision\"),\n + \t\t\t N_(\"replay onto given commit\")),\n + \t\tOPT_BOOL(0, \"contained\", &contained,\n +-\t\t\t N_(\"advance all branches contained in revision-range\")),\n ++\t\t\t N_(\"update all branches that point at commits in \")),\n + \t\tOPT_STRING(0, \"ref-action\", &ref_action,\n + \t\t\t N_(\"mode\"),\n + \t\t\t N_(\"control ref update behavior (update|print)\")),\n3: ca83b00343d = 3: 4e851fdff34 doc: replay: link section using markup\n\nbase-commit: bdc5341ff65278a3cc80b2e8a02a2f02aa1fac06\n-- \n2.52.0.10.g08704017180\n\n"},{"id":"532131","messageId":"V2_no_output_on_conflict.130@msgid.xyz","threadId":"64591","inReplyTo":"V2_CV_replay_conflict.12f@msgid.xyz","subject":"[PATCH v2 1/3] doc: replay: mention no output on conflicts","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-12-13T13:46:56Z","receivedAt":"2025-12-13T13:47:40Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"From: Kristoffer Haugsbakk \n\nSome commands will produce output on stderr if there are conflicts, but\ngit-replay(1) is completely silent. Explicitly spell that out.\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n Documentation/git-replay.adoc | 4 ++++\n 1 file changed, 4 insertions(+)\n\ndiff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc\nindex dcb26e8a8e8..6fbb527b9d8 100644\n--- a/Documentation/git-replay.adoc\n+++ b/Documentation/git-replay.adoc\n@@ -81,6 +81,10 @@ the shape of the history being replayed. When using `--advance`, the\n number of refs updated is always one, but for `--onto`, it can be one\n or more (rebasing multiple branches simultaneously is supported).\n \n+There is no stderr output on conflicts; see the <> section below.\n+\n+[[exit-status]]\n EXIT STATUS\n -----------\n \n-- \n2.52.0.10.g08704017180\n\n"},{"id":"532132","messageId":"V2_doc_replay_--contained.131@msgid.xyz","threadId":"64591","inReplyTo":"V2_CV_replay_conflict.12f@msgid.xyz","subject":"[PATCH v2 2/3] replay: improve --contained and add to doc","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-12-13T13:46:57Z","receivedAt":"2025-12-13T13:48:01Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"From: Kristoffer Haugsbakk \n\nThere is no documentation for `--contained`.\n\nStart by copying the text from `replay_options` in `builtin/\nreplay.c`. But some people think that the existing text is a\nbit unclear; what does it mean for a branch to be contained\nin a revision range? Let’s include the implied commits here:\nthe branches that point at commits in the range.\n\nAlso use “update” instead of “advance”. “Update” is the verb\ncommonly used in this context.\n\nHelped-by: Phillip Wood \nHelped-by: Junio C Hamano \nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v2:\n \n Don’t just copy `--contained` over. Improve it on both sites after discussing\n with reviewers.\n \n Also mention that `--onto` is required.\n\n Documentation/git-replay.adoc | 4 ++++\n builtin/replay.c | 2 +-\n 2 files changed, 5 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc\nindex 6fbb527b9d8..1e2469b9034 100644\n--- a/Documentation/git-replay.adoc\n+++ b/Documentation/git-replay.adoc\n@@ -42,6 +42,10 @@ The history is replayed on top of the and is updated to\n point at the tip of the resulting history. This is different from `--onto`,\n which uses the target only as a starting point without updating it.\n \n+--contained::\n+\tUpdate all branches that point at commits in\n+\t. Requires `--onto`.\n+\n --ref-action[=]::\n \tControl how references are updated. The mode can be:\n +\ndiff --git a/builtin/replay.c b/builtin/replay.c\nindex 6606a2c94bc..9e5ad64cad6 100644\n--- a/builtin/replay.c\n+++ b/builtin/replay.c\n@@ -377,7 +377,7 @@ int cmd_replay(int argc,\n \t\t\t N_(\"revision\"),\n \t\t\t N_(\"replay onto given commit\")),\n \t\tOPT_BOOL(0, \"contained\", &contained,\n-\t\t\t N_(\"advance all branches contained in revision-range\")),\n+\t\t\t N_(\"update all branches that point at commits in \")),\n \t\tOPT_STRING(0, \"ref-action\", &ref_action,\n \t\t\t N_(\"mode\"),\n \t\t\t N_(\"control ref update behavior (update|print)\")),\n-- \n2.52.0.10.g08704017180\n\n"},{"id":"532133","messageId":"V2_link_OUTPUT_section.132@msgid.xyz","threadId":"64591","inReplyTo":"V2_CV_replay_conflict.12f@msgid.xyz","subject":"[PATCH v2 3/3] doc: replay: link section using markup","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-12-13T13:46:58Z","receivedAt":"2025-12-13T13:48:21Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"From: Kristoffer Haugsbakk \n\nSigned-off-by: Kristoffer Haugsbakk \n---\n Documentation/git-replay.adoc | 3 ++-\n 1 file changed, 2 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc\nindex 1e2469b9034..22fd1b271af 100644\n--- a/Documentation/git-replay.adoc\n+++ b/Documentation/git-replay.adoc\n@@ -19,7 +19,7 @@ the working tree and the index untouched. By default, updates the\n relevant references using an atomic transaction (all refs update or\n none). Use `--ref-action=print` to avoid automatic ref updates and\n instead get update commands that can be piped to `git update-ref --stdin`\n-(see the OUTPUT section below).\n+(see the <> section below).\n \n THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE.\n \n@@ -67,6 +67,7 @@ The default mode can be configured via the `replay.refAction` configuration vari\n \n include::rev-list-options.adoc[]\n \n+[[output]]\n OUTPUT\n ------\n \n-- \n2.52.0.10.g08704017180\n\n"},{"id":"532181","messageId":"8fa21ce8-1e02-419f-b82a-0e4a41f7e2d8@gmail.com","threadId":"64591","inReplyTo":"V2_CV_replay_conflict.12f@msgid.xyz","subject":"Re: [PATCH v2 0/3] doc: replay: improvements like \"mention no output on conflicts\"","fromName":"Phillip Wood","fromEmail":"phillip.wood123@gmail.com","sentAt":"2025-12-15T10:13:16Z","receivedAt":"2025-12-15T10:13:20Z","isPatch":true,"sender":{"key":"phillip.wood@dunelm.org.uk","avatar":null},"body":"On 13/12/2025 13:46, kristofferhaugsbakk@fastmail.com wrote:\n> From: Kristoffer Haugsbakk \n> \n> Explicitly say that conflicts do not give any output. I found this a bit\n> confusing with the current doc since I am used to other commands\n> complaining loudly.\n> \n> § Changes in v2\n> \n> Patch 2/3: improve `--contained` and mention that it requires `--onto`.\n\nThe new text looks good, I don't really understand the commit message \nbut the intent of the change is clear enough.\n\nThanks for improving the documentation\n\nPhillip\n\n> Kristoffer Haugsbakk (3):\n> doc: replay: mention no output on conflicts\n> replay: improve --contained and add to doc\n> doc: replay: link section using markup\n> \n> Documentation/git-replay.adoc | 11 ++++++++++-\n> builtin/replay.c | 2 +-\n> 2 files changed, 11 insertions(+), 2 deletions(-)\n> \n> Interdiff against v1:\n> diff --git a/Documentation/git-replay.adoc b/Documentation/git-replay.adoc\n> index 04944a5fa23..22fd1b271af 100644\n> --- a/Documentation/git-replay.adoc\n> +++ b/Documentation/git-replay.adoc\n> @@ -43,7 +43,8 @@ point at the tip of the resulting history. This is different from `--onto`,\n> which uses the target only as a starting point without updating it.\n> \n> --contained::\n> -\tAdvance all branches contained in .\n> +\tUpdate all branches that point at commits in\n> +\t. Requires `--onto`.\n> \n> --ref-action[=]::\n> \tControl how references are updated. The mode can be:\n> diff --git a/builtin/replay.c b/builtin/replay.c\n> index 6606a2c94bc..9e5ad64cad6 100644\n> --- a/builtin/replay.c\n> +++ b/builtin/replay.c\n> @@ -377,7 +377,7 @@ int cmd_replay(int argc,\n> \t\t\t N_(\"revision\"),\n> \t\t\t N_(\"replay onto given commit\")),\n> \t\tOPT_BOOL(0, \"contained\", &contained,\n> -\t\t\t N_(\"advance all branches contained in revision-range\")),\n> +\t\t\t N_(\"update all branches that point at commits in \")),\n> \t\tOPT_STRING(0, \"ref-action\", &ref_action,\n> \t\t\t N_(\"mode\"),\n> \t\t\t N_(\"control ref update behavior (update|print)\")),\n> Range-diff against v1:\n> 1: b9ec24c8b8f = 1: b9ec24c8b8f doc: replay: mention no output on conflicts\n> 2: 02a80ee87b5 ! 2: 27bf2ac7a0b doc: replay: document --contained\n> @@ Metadata\n> Author: Kristoffer Haugsbakk \n> \n> ## Commit message ##\n> - doc: replay: document --contained\n> + replay: improve --contained and add to doc\n> \n> - Copy the text from `replay_options` in `builtin/replay.c`.\n> + There is no documentation for `--contained`.\n> \n> + Start by copying the text from `replay_options` in `builtin/\n> + replay.c`. But some people think that the existing text is a\n> + bit unclear; what does it mean for a branch to be contained\n> + in a revision range? Let’s include the implied commits here:\n> + the branches that point at commits in the range.\n> +\n> + Also use “update” instead of “advance”. “Update” is the verb\n> + commonly used in this context.\n> +\n> + Helped-by: Phillip Wood \n> + Helped-by: Junio C Hamano \n> Signed-off-by: Kristoffer Haugsbakk \n> \n> +\n> + ## Notes (series) ##\n> + v2:\n> +\n> + Don’t just copy `--contained` over. Improve it on both sites after discussing\n> + with reviewers.\n> +\n> + Also mention that `--onto` is required.\n> +\n> ## Documentation/git-replay.adoc ##\n> @@ Documentation/git-replay.adoc: The history is replayed on top of the and is updated to\n> point at the tip of the resulting history. This is different from `--onto`,\n> which uses the target only as a starting point without updating it.\n> \n> +--contained::\n> -+\tAdvance all branches contained in .\n> ++\tUpdate all branches that point at commits in\n> ++\t. Requires `--onto`.\n> +\n> --ref-action[=]::\n> \tControl how references are updated. The mode can be:\n> +\n> +\n> + ## builtin/replay.c ##\n> +@@ builtin/replay.c: int cmd_replay(int argc,\n> + \t\t\t N_(\"revision\"),\n> + \t\t\t N_(\"replay onto given commit\")),\n> + \t\tOPT_BOOL(0, \"contained\", &contained,\n> +-\t\t\t N_(\"advance all branches contained in revision-range\")),\n> ++\t\t\t N_(\"update all branches that point at commits in \")),\n> + \t\tOPT_STRING(0, \"ref-action\", &ref_action,\n> + \t\t\t N_(\"mode\"),\n> + \t\t\t N_(\"control ref update behavior (update|print)\")),\n> 3: ca83b00343d = 3: 4e851fdff34 doc: replay: link section using markup\n> \n> base-commit: bdc5341ff65278a3cc80b2e8a02a2f02aa1fac06\n\n"},{"id":"532184","messageId":"bf3f3633-5d0d-4fa4-9706-d99e32a3f91d@app.fastmail.com","threadId":"64591","inReplyTo":"8fa21ce8-1e02-419f-b82a-0e4a41f7e2d8@gmail.com","subject":"Re: [PATCH v2 0/3] doc: replay: improvements like \"mention no output on conflicts\"","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-12-15T11:59:07Z","receivedAt":"2025-12-15T11:59:29Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"On Mon, Dec 15, 2025, at 11:13, Phillip Wood wrote:\n> On 13/12/2025 13:46, kristofferhaugsbakk@fastmail.com wrote:\n>> From: Kristoffer Haugsbakk \n>>\n>> Explicitly say that conflicts do not give any output. I found this a bit\n>> confusing with the current doc since I am used to other commands\n>> complaining loudly.\n>>\n>> § Changes in v2\n>>\n>> Patch 2/3: improve `--contained` and mention that it requires `--onto`.\n>\n> The new text looks good, I don't really understand the commit message\n> but the intent of the change is clear enough.\n>\n> Thanks for improving the documentation\n\nThank you. But I’m not glad that the commit message is not clear. I\nwould need some guidance on how to write it because it seems clear to\nme. Something with my brain state I guess.\n"},{"id":"532223","messageId":"xmqqa4zj6zhv.fsf@gitster.g","threadId":"64591","inReplyTo":"bf3f3633-5d0d-4fa4-9706-d99e32a3f91d@app.fastmail.com","subject":"Re: [PATCH v2 0/3] doc: replay: improvements like \"mention no output on conflicts\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-12-16T00:29:00Z","receivedAt":"2025-12-16T00:29:03Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Kristoffer Haugsbakk\" writes:\n\n> On Mon, Dec 15, 2025, at 11:13, Phillip Wood wrote:\n>> On 13/12/2025 13:46, kristofferhaugsbakk@fastmail.com wrote:\n>>> From: Kristoffer Haugsbakk \n>>>\n>>> Explicitly say that conflicts do not give any output. I found this a bit\n>>> confusing with the current doc since I am used to other commands\n>>> complaining loudly.\n>>>\n>>> § Changes in v2\n>>>\n>>> Patch 2/3: improve `--contained` and mention that it requires `--onto`.\n>>\n>> The new text looks good, I don't really understand the commit message\n>> but the intent of the change is clear enough.\n>>\n>> Thanks for improving the documentation\n>\n> Thank you. But I’m not glad that the commit message is not clear. I\n> would need some guidance on how to write it because it seems clear to\n> me. Something with my brain state I guess.\n\nThey are already in 'next', but let's see if there are pain points.\n\ncommit 8467c95419acaa826a6c1ca0db0f36a3fd614ae4\nAuthor: Kristoffer Haugsbakk \nDate: Sat Dec 13 14:46:56 2025 +0100\n\n doc: replay: mention no output on conflicts\n \n Some commands will produce output on stderr if there are conflicts, but\n git-replay(1) is completely silent. Explicitly spell that out.\n \n Signed-off-by: Kristoffer Haugsbakk \n Signed-off-by: Junio C Hamano \n\nLooks clear enough to me.\n\n\ncommit 03d7c9c457ba68f28269dcd607b9026ea6c6c9c8\nAuthor: Kristoffer Haugsbakk \nDate: Sat Dec 13 14:46:57 2025 +0100\n\n replay: improve --contained and add to doc\n \n There is no documentation for `--contained`.\n \n Start by copying the text from `replay_options` in `builtin/\n replay.c`. But some people think that the existing text is a\n bit unclear; what does it mean for a branch to be contained\n in a revision range? Let’s include the implied commits here:\n the branches that point at commits in the range.\n \n Also use “update” instead of “advance”. “Update” is the verb\n commonly used in this context.\n \n Helped-by: Phillip Wood \n Helped-by: Junio C Hamano \n Signed-off-by: Kristoffer Haugsbakk \n Signed-off-by: Junio C Hamano \n\nAs to the title, \"improve --contained\" hinted me there is some code\nchanges for behaviour, but there isn't, so that part may have been a\nbit misleading. \"improve short-help of --contained and add to doc\",\nperhaps.\n\nI think the problem people found in the second paragraph is because\nit is so unclear what it is talking about if you read it without\nlooking at the patch text. You started from the existing \"advance\nall branches contained in revision-range\", taken from the existing\nshort-help in replay_options[]. But without seeing that \"branches\ncontained\" text, it is natural that readers find it hard to judge\nthe validity of \"But some people think that...\" claim themselves.\n\nIf I were writing this (but I will not rewind 'next' to do so),\nI'd say something like:\n\n replay: improve the help of the `--contained` option and document it\n\n \"git replay -h\" explains \"--contained\" as\n\n\tadvance all branches contained in revision-range\n\n but it may be unclear when exactly a branch is contained in a\n revision range. Because the command updates a branch that\n points at a commit that gets rewritten to point at the result of\n the rewrite, \"update branches that point at commits in the\n range\" says what we want to say more clearly and concisely.\n\n The \"--contained\" option has no description in \"git replay\"\n documentation. Use the improved phrase there, too.\n\nprobably. In any case, it is a good exercise to see if the proposed\nlog message can be easily understood without looking at the code\nchange.\n\n\ncommit 9ba08b30a117e6925a9e5e87c92b37de7396d3a4\nAuthor: Kristoffer Haugsbakk \nDate: Sat Dec 13 14:46:58 2025 +0100\n\n doc: replay: link section using markup\n \n Signed-off-by: Kristoffer Haugsbakk \n Signed-off-by: Junio C Hamano \n\nLooking good.\n"},{"id":"532274","messageId":"df29f24b-f545-47d1-ba4e-9ef25f01934e@gmail.com","threadId":"64591","inReplyTo":"xmqqa4zj6zhv.fsf@gitster.g","subject":"Re: [PATCH v2 0/3] doc: replay: improvements like \"mention no output on conflicts\"","fromName":"Phillip Wood","fromEmail":"phillip.wood123@gmail.com","sentAt":"2025-12-16T14:25:06Z","receivedAt":"2025-12-16T14:25:09Z","isPatch":true,"sender":{"key":"phillip.wood@dunelm.org.uk","avatar":null},"body":"On 16/12/2025 00:29, Junio C Hamano wrote:\n> \"Kristoffer Haugsbakk\" writes:\n>>\n>> Thank you. But I’m not glad that the commit message is not clear. I\n>> would need some guidance on how to write it because it seems clear to\n>> me. Something with my brain state I guess.\n> \n> commit 03d7c9c457ba68f28269dcd607b9026ea6c6c9c8\n> Author: Kristoffer Haugsbakk \n> Date: Sat Dec 13 14:46:57 2025 +0100\n> \n> replay: improve --contained and add to doc\n> \n> There is no documentation for `--contained`.\n> \n> Start by copying the text from `replay_options` in `builtin/\n> replay.c`. But some people think that the existing text is a\n> bit unclear; what does it mean for a branch to be contained\n> in a revision range? Let’s include the implied commits here:\n> the branches that point at commits in the range.\n> \n> Also use “update” instead of “advance”. “Update” is the verb\n> commonly used in this context.\n> \n> Helped-by: Phillip Wood \n> Helped-by: Junio C Hamano \n> Signed-off-by: Kristoffer Haugsbakk \n> Signed-off-by: Junio C Hamano \n> \n> As to the title, \"improve --contained\" hinted me there is some code\n> changes for behaviour, but there isn't, so that part may have been a\n> bit misleading. \"improve short-help of --contained and add to doc\",\n> perhaps.\n> \n> I think the problem people found in the second paragraph is because\n> it is so unclear what it is talking about if you read it without\n> looking at the patch text. You started from the existing \"advance\n> all branches contained in revision-range\", taken from the existing\n> short-help in replay_options[]. But without seeing that \"branches\n> contained\" text, it is natural that readers find it hard to judge\n> the validity of \"But some people think that...\" claim themselves.\n\nThat's a good summary of what I found confusing. I like you suggested \nmessage below but I agree it is not worth messing with it now it is in next.\n\nThanks\n\nPhillip\n\n> If I were writing this (but I will not rewind 'next' to do so),\n> I'd say something like:\n> \n> replay: improve the help of the `--contained` option and document it\n> \n> \"git replay -h\" explains \"--contained\" as\n> \n> \tadvance all branches contained in revision-range\n> \n> but it may be unclear when exactly a branch is contained in a\n> revision range. Because the command updates a branch that\n> points at a commit that gets rewritten to point at the result of\n> the rewrite, \"update branches that point at commits in the\n> range\" says what we want to say more clearly and concisely.\n> \n> The \"--contained\" option has no description in \"git replay\"\n> documentation. Use the improved phrase there, too.\n> \n> probably. In any case, it is a good exercise to see if the proposed\n> log message can be easily understood without looking at the code\n> change.\n> \n> \n> commit 9ba08b30a117e6925a9e5e87c92b37de7396d3a4\n> Author: Kristoffer Haugsbakk \n> Date: Sat Dec 13 14:46:58 2025 +0100\n> \n> doc: replay: link section using markup\n> \n> Signed-off-by: Kristoffer Haugsbakk \n> Signed-off-by: Junio C Hamano \n> \n> Looking good.\n\n"},{"id":"532603","messageId":"8e7e09ea-190b-4df6-b013-733334185bb8@app.fastmail.com","threadId":"64591","inReplyTo":"xmqqa4zj6zhv.fsf@gitster.g","subject":"Re: [PATCH v2 0/3] doc: replay: improvements like \"mention no output on conflicts\"","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-12-20T19:34:37Z","receivedAt":"2025-12-20T19:34:59Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"On Tue, Dec 16, 2025, at 01:29, Junio C Hamano wrote:\n> \"Kristoffer Haugsbakk\" writes:\n>>[snip]\n>> Thank you. But I’m not glad that the commit message is not clear. I\n>> would need some guidance on how to write it because it seems clear to\n>> me. Something with my brain state I guess.\n>\n> They are already in 'next', but let's see if there are pain points.\n>\n>[snip]\n> commit 03d7c9c457ba68f28269dcd607b9026ea6c6c9c8\n> Author: Kristoffer Haugsbakk \n> Date: Sat Dec 13 14:46:57 2025 +0100\n>\n> replay: improve --contained and add to doc\n>\n> There is no documentation for `--contained`.\n>\n> Start by copying the text from `replay_options` in `builtin/\n> replay.c`. But some people think that the existing text is a\n> bit unclear; what does it mean for a branch to be contained\n> in a revision range? Let’s include the implied commits here:\n> the branches that point at commits in the range.\n>\n> Also use “update” instead of “advance”. “Update” is the verb\n> commonly used in this context.\n>\n> Helped-by: Phillip Wood \n> Helped-by: Junio C Hamano \n> Signed-off-by: Kristoffer Haugsbakk \n> Signed-off-by: Junio C Hamano \n>\n> As to the title, \"improve --contained\" hinted me there is some code\n> changes for behaviour, but there isn't, so that part may have been a\n> bit misleading. \"improve short-help of --contained and add to doc\",\n> perhaps.\n\nOh right, of course. The original area was `doc` and in that case this\nwould have been fine. But I didn’t consider the `replay` area. So now it\nlooks like the `--contained` option logic has been changed.\n\n>\n> I think the problem people found in the second paragraph is because\n> it is so unclear what it is talking about if you read it without\n> looking at the patch text. You started from the existing \"advance\n> all branches contained in revision-range\", taken from the existing\n> short-help in replay_options[]. But without seeing that \"branches\n> contained\" text, it is natural that readers find it hard to judge\n> the validity of \"But some people think that...\" claim themselves.\n>\n> If I were writing this (but I will not rewind 'next' to do so),\n> I'd say something like:\n>\n> replay: improve the help of the `--contained` option and document it\n>\n> \"git replay -h\" explains \"--contained\" as\n>\n> \tadvance all branches contained in revision-range\n>\n> but it may be unclear when exactly a branch is contained in a\n> revision range. Because the command updates a branch that\n> points at a commit that gets rewritten to point at the result of\n> the rewrite, \"update branches that point at commits in the\n> range\" says what we want to say more clearly and concisely.\n>\n> The \"--contained\" option has no description in \"git replay\"\n> documentation. Use the improved phrase there, too.\n>\n> probably. In any case, it is a good exercise to see if the proposed\n> log message can be easily understood without looking at the code\n> change.\n\nOkay, now I get it. It turns out I’m still learning how to write commit\nmessages with the right amount of context.\n\nAnd thanks to Phillip for confirming.\n\n>[snip]\n"}]}