{"thread":{"id":"60928","subject":"[PATCH] branch: rework the descriptions of rename and copy operations","startedAt":"2024-02-15T18:42:41Z","lastAt":"2024-03-02T16:18:23Z","messageCount":36,"participants":["Dragan Simic","Kristoffer Haugsbakk","Junio C Hamano","Rubén Justo","Kyle Lippincott"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"488748","messageId":"3cbc78bb5729f304b30bf37a18d1762af553aa00.1708022441.git.dsimic@manjaro.org","threadId":"60928","inReplyTo":null,"subject":"[PATCH] branch: rework the descriptions of rename and copy operations","fromName":"Dragan Simic","fromEmail":"dsimic@manjaro.org","sentAt":"2024-02-15T18:42:32Z","receivedAt":"2024-02-15T18:42:41Z","isPatch":true,"sender":{"key":"dsimic@manjaro.org","avatar":null},"body":"Move the descriptions of the and arguments to the\ndescriptions of the branch rename and copy operations, where they naturally\nbelong. Also, improve the descriptions of these two branch operations and,\nfor completeness, describe the outcomes of forced operations.\n\nDescribing the arguments together with their respective operations, instead\nof describing them separately in a rather unfortunate attempt to squeeze more\nmeaning out of fewer words, flows much better and makes the git-branch(1)\nman page significantly more usable.\n\nThe subsequent improvements shall continue this approach by either dissolving\nas many sentences from the \"Description\" section into the \"Options\" section,\nor by having those sentences converted into some kind of more readable and\nbetter flowing prose, as already discussed and outlined. [1][2]\n\n[1] https://lore.kernel.org/git/xmqqttmmlahf.fsf@gitster.g/T/#u\n[2] https://lore.kernel.org/git/xmqq8r4zln08.fsf@gitster.g/T/#u\n\nSigned-off-by: Dragan Simic \n---\n\nNotes:\n This patch was originally named \"branch: clarify and \n terms further\", submitted and discussed in another thread, [3] but the nature\n of the patch has changed, causing the patch subject to be adjusted to match.\n \n Consequently, this is effectively version 2 of the patch, which includes\n detailed feedback from Kyle and Junio, who suggested moving/adding the\n argument descriptions to their respective commands. This resulted in more\n significant changes to the contents of the git-branch(1) man page, in an\n attempt to make it more readable.\n \n [3] https://lore.kernel.org/git/e2eb777bca8ffeec42bdd684837d28dd52cfc9c3.1707136999.git.dsimic@manjaro.org/T/#u\n\n Documentation/git-branch.txt | 44 +++++++++++++++---------------------\n 1 file changed, 18 insertions(+), 26 deletions(-)\n\ndiff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt\nindex 0b0844293235..370ea43c0380 100644\n--- a/Documentation/git-branch.txt\n+++ b/Documentation/git-branch.txt\n@@ -72,16 +72,6 @@ the remote-tracking branch. This behavior may be changed via the global\n overridden by using the `--track` and `--no-track` options, and\n changed later using `git branch --set-upstream-to`.\n \n-With a `-m` or `-M` option, will be renamed to .\n-If had a corresponding reflog, it is renamed to match\n-, and a reflog entry is created to remember the branch\n-renaming. If exists, -M must be used to force the rename\n-to happen.\n-\n-The `-c` and `-C` options have the exact same semantics as `-m` and\n-`-M`, except instead of the branch being renamed, it will be copied to a\n-new name, along with its config and reflog.\n-\n With a `-d` or `-D` option, `` will be deleted. You may\n specify more than one branch for deletion. If the branch currently\n has a reflog then the reflog will also be deleted.\n@@ -128,18 +118,28 @@ Note that 'git branch -f []', even with '-f',\n refuses to change an existing branch `` that is checked out\n in another worktree linked to the same repository.\n \n--m::\n---move::\n-\tMove/rename a branch, together with its config and reflog.\n+-m [] ::\n+--move [] ::\n+\tRename an existing branch , which if not specified defaults\n+\tto the current branch, to . The configuration variables\n+\tfor the branch and its reflog are also renamed appropriately\n+\tto be used with . Renaming fails if branch \n+\talready exists, but you can use `-M` or `--move --force` to overwrite\n+\tthe files in existing branch while renaming.\n \n--M::\n+-M [] ::\n \tShortcut for `--move --force`.\n \n--c::\n---copy::\n-\tCopy a branch, together with its config and reflog.\n+-c [] ::\n+--copy [] ::\n+\tCopy an existing branch , which if not specified defaults\n+\tto the current branch, to . The configuration variables\n+\tfor the branch and its reflog are also copied appropriately\n+\tto be used with . Copying fails if branch \n+\talready exists, but you can use `-C` or `--copy --force` to overwrite\n+\tthe files in existing branch while copying.\n \n--C::\n+-C [] ::\n \tShortcut for `--copy --force`.\n \n --color[=]::\n@@ -311,14 +311,6 @@ superproject's \"origin/main\", but tracks the submodule's \"origin/main\".\n \tgiven as a branch name, a commit-id, or a tag. If this\n \toption is omitted, the current HEAD will be used instead.\n \n-::\n-\tThe name of an existing branch. If this option is omitted,\n-\tthe name of the current branch will be used instead.\n-\n-::\n-\tThe new name for an existing branch. The same restrictions as for\n-\t apply.\n-\n --sort=::\n \tSort based on the key given. Prefix `-` to sort in descending\n \torder of the value. You may use the --sort= option\n"},{"id":"488752","messageId":"f9ec6d31-7158-4381-9701-06fcb33f2e83@app.fastmail.com","threadId":"60928","inReplyTo":"3cbc78bb5729f304b30bf37a18d1762af553aa00.1708022441.git.dsimic@manjaro.org","subject":"Re: [PATCH] branch: rework the descriptions of rename and copy operations","fromName":"Kristoffer Haugsbakk","fromEmail":"code@khaugsbakk.name","sentAt":"2024-02-15T19:28:45Z","receivedAt":"2024-02-15T19:29:41Z","isPatch":true,"sender":{"key":"code@khaugsbakk.name","avatar":"https://avatars.githubusercontent.com/u/2229597?v=4"},"body":"Hey Dragan\n\n(I’m adding some Cc from the previous round)\n\nOn Thu, Feb 15, 2024, at 19:42, Dragan Simic wrote:\n> Move the descriptions of the and arguments to the\n> descriptions of the branch rename and copy operations, where they naturally\n> belong. Also, improve the descriptions of these two branch operations and,\n> for completeness, describe the outcomes of forced operations.\n>\n> Describing the arguments together with their respective operations, instead\n> of describing them separately in a rather unfortunate attempt to squeeze more\n> meaning out of fewer words, flows much better and makes the git-branch(1)\n> man page significantly more usable.\n\nExcellent.\n\n>\n> The subsequent improvements shall continue this approach by either dissolving\n> as many sentences from the \"Description\" section into the \"Options\" section,\n> or by having those sentences converted into some kind of more readable and\n> better flowing prose, as already discussed and outlined. [1][2]\n>\n> [1] https://lore.kernel.org/git/xmqqttmmlahf.fsf@gitster.g/T/#u\n> [2] https://lore.kernel.org/git/xmqq8r4zln08.fsf@gitster.g/T/#u\n\nSince this is a one-patch series, it wasn’t clear to me what “subsequent\nimprovements” was referring to without following the links. By following\nthe links it looks like plans have been made to improve this man page\nfurther. Maybe the commit message could either state this intent more\nassertively or commit to it less (like “we might in the future…”)? So\nthat the links become supplementary information instead of seemingly\nfilling in some blanks.\n\n(If I read this part correctly.)\n\n> --m::\n> ---move::\n> -\tMove/rename a branch, together with its config and reflog.\n> +-m [] ::\n> +--move [] ::\n> +\tRename an existing branch , which if not specified defaults\n> +\tto the current branch, to . The configuration variables\n\nI had to read the first sentence a few times in order to understand what\nthe “which” part was saying (which seems to come from [1] by Junio). How\nabout letting it trail the sentence?\n\n « Rename an existing branch `` to ``, with\n `` defaulting to the current branch if not specified.\n\n🔗 1: https://lore.kernel.org/git/xmqqttmmlahf.fsf@gitster.g/\n\n> +\tfor the branch and its reflog are also renamed appropriately\n> +\tto be used with . Renaming fails if branch \n> +\talready exists, but you can use `-M` or `--move --force` to overwrite\n> +\tthe files in existing branch while renaming.\n\n“the files” refers to the branch configuration and the reflog? People\nwho read the man pages might not know that the reflogs are implemented\nas files and get tripped up. Maybe “to overwrite” could be left\nunstated?\n\nOr maybe I just misunderstood this part.\n\nThis patch also drops this part. Shouldn’t this be noted?\n\n « , and a reflog entry is created to remember the branch renaming.\n\nRight now it looks like (reads like) the reflog is moved and an entry is\nnot made about it.\n\n>\n> --M::\n> +-M [] ::\n> \tShortcut for `--move --force`.\n>\n> --c::\n> ---copy::\n> -\tCopy a branch, together with its config and reflog.\n> +-c [] ::\n> +--copy [] ::\n> +\tCopy an existing branch , which if not specified defaults\n> +\tto the current branch, to . The configuration variables\n> +\tfor the branch and its reflog are also copied appropriately\n> +\tto be used with . Copying fails if branch \n> +\talready exists, but you can use `-C` or `--copy --force` to overwrite\n> +\tthe files in existing branch while copying.\n"},{"id":"488753","messageId":"6d3cf1220823e793a5244d187627ce97@manjaro.org","threadId":"60928","inReplyTo":"f9ec6d31-7158-4381-9701-06fcb33f2e83@app.fastmail.com","subject":"Re: [PATCH] branch: rework the descriptions of rename and copy operations","fromName":"Dragan Simic","fromEmail":"dsimic@manjaro.org","sentAt":"2024-02-15T19:47:39Z","receivedAt":"2024-02-15T19:47:58Z","isPatch":true,"sender":{"key":"dsimic@manjaro.org","avatar":null},"body":"Hello Kristoffer,\n\nOn 2024-02-15 20:28, Kristoffer Haugsbakk wrote:\n> (I’m adding some Cc from the previous round)\n\nThanks, I realised that to be missing like two seconds after sending\nthe patch to the list. :/\n\n> On Thu, Feb 15, 2024, at 19:42, Dragan Simic wrote:\n>> Move the descriptions of the and arguments to \n>> the\n>> descriptions of the branch rename and copy operations, where they \n>> naturally\n>> belong. Also, improve the descriptions of these two branch operations \n>> and,\n>> for completeness, describe the outcomes of forced operations.\n>> \n>> Describing the arguments together with their respective operations, \n>> instead\n>> of describing them separately in a rather unfortunate attempt to \n>> squeeze more\n>> meaning out of fewer words, flows much better and makes the \n>> git-branch(1)\n>> man page significantly more usable.\n> \n> Excellent.\n\nThanks, I'm glad that you like it. :)\n\n>> The subsequent improvements shall continue this approach by either \n>> dissolving\n>> as many sentences from the \"Description\" section into the \"Options\" \n>> section,\n>> or by having those sentences converted into some kind of more readable \n>> and\n>> better flowing prose, as already discussed and outlined. [1][2]\n>> \n>> [1] https://lore.kernel.org/git/xmqqttmmlahf.fsf@gitster.g/T/#u\n>> [2] https://lore.kernel.org/git/xmqq8r4zln08.fsf@gitster.g/T/#u\n> \n> Since this is a one-patch series, it wasn’t clear to me what \n> “subsequent\n> improvements” was referring to without following the links. By \n> following\n> the links it looks like plans have been made to improve this man page\n> further. Maybe the commit message could either state this intent more\n> assertively or commit to it less (like “we might in the future…”)? So\n> that the links become supplementary information instead of seemingly\n> filling in some blanks.\n> \n> (If I read this part correctly.)\n\nIt refers to the already planned further rework of the git-branch(1) man\npage, which I intend to follow, but also leaves a TODO note to anyone \nelse\nlooking at the repository history, in case I end up not following the \nplan\nfor some reason. I hope this makes it more clear.\n\n>> --m::\n>> ---move::\n>> -\tMove/rename a branch, together with its config and reflog.\n>> +-m [] ::\n>> +--move [] ::\n>> +\tRename an existing branch , which if not specified \n>> defaults\n>> +\tto the current branch, to . The configuration variables\n> \n> I had to read the first sentence a few times in order to understand \n> what\n> the “which” part was saying (which seems to come from [1] by Junio). \n> How\n> about letting it trail the sentence?\n> \n> « Rename an existing branch `` to ``, with\n> `` defaulting to the current branch if not specified.\n\nMakes sense, maybe even something like this for the v2:\n\n Rename an existing branch to ; if not \nspecified,\n defaults to the current branch.\n\n> 🔗 1: https://lore.kernel.org/git/xmqqttmmlahf.fsf@gitster.g/\n> \n>> +\tfor the branch and its reflog are also renamed \n>> appropriately\n>> +\tto be used with . Renaming fails if branch \n>> +\talready exists, but you can use `-M` or `--move --force` to \n>> overwrite\n>> +\tthe files in existing branch while renaming.\n> \n> “the files” refers to the branch configuration and the reflog? People\n> who read the man pages might not know that the reflogs are implemented\n> as files and get tripped up. Maybe “to overwrite” could be left\n> unstated?\n> \n> Or maybe I just misunderstood this part.\n\nBasically, the internal logic just overwrites the files, whatever the\nfiles actually are, and issues warning messages about that. Frankly,\nI'm not sure that having \"--force\" available is the safest possible \nthing,\nbut it's already there and needs documenting.\n\nThus, \"the files\" refers to just that, the files in the destination\nbranch that pretty much gets garbled after forced operations.\n\nPerhaps it could be worded like this in the v2:\n\n ... but you can use `-M` or `--move --force` to overwrite the \ncontents\n of the existing branch while renaming.\n\n> This patch also drops this part. Shouldn’t this be noted?\n> \n> « , and a reflog entry is created to remember the branch renaming.\n> \n> Right now it looks like (reads like) the reflog is moved and an entry \n> is\n> not made about it.\n\nGood point, thanks. I'll address that in the v2.\n\n>> --M::\n>> +-M [] ::\n>> \tShortcut for `--move --force`.\n>> \n>> --c::\n>> ---copy::\n>> -\tCopy a branch, together with its config and reflog.\n>> +-c [] ::\n>> +--copy [] ::\n>> +\tCopy an existing branch , which if not specified defaults\n>> +\tto the current branch, to . The configuration variables\n>> +\tfor the branch and its reflog are also copied \n>> appropriately\n>> +\tto be used with . Copying fails if branch \n>> +\talready exists, but you can use `-C` or `--copy --force` to \n>> overwrite\n>> +\tthe files in existing branch while copying.\n"},{"id":"488755","messageId":"xmqqedddo3ym.fsf@gitster.g","threadId":"60928","inReplyTo":"f9ec6d31-7158-4381-9701-06fcb33f2e83@app.fastmail.com","subject":"Re: [PATCH] branch: rework the descriptions of rename and copy operations","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-02-15T20:41:21Z","receivedAt":"2024-02-15T20:41:24Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Kristoffer Haugsbakk\" writes:\n\n> (If I read this part correctly.)\n>\n>> --m::\n>> ---move::\n>> -\tMove/rename a branch, together with its config and reflog.\n>> +-m [] ::\n>> +--move [] ::\n>> +\tRename an existing branch , which if not specified defaults\n>> +\tto the current branch, to . The configuration variables\n>\n> I had to read the first sentence a few times in order to understand what\n> the “which” part was saying (which seems to come from [1] by Junio). How\n> about letting it trail the sentence?\n>\n> « Rename an existing branch `` to ``, with\n> `` defaulting to the current branch if not specified.\n\nYeah, insertion of \"if not specified\" in the middle made the\nresulting text unnecessarily hard to follow, and moving it to the\nend is a fine fix. But I think we can just drop it (in other words,\nwe already said \"defaulting to\" and that should be sufficient).\n\n>> +\tfor the branch and its reflog are also renamed appropriately\n>> +\tto be used with . Renaming fails if branch \n>> +\talready exists, but you can use `-M` or `--move --force` to overwrite\n>> +\tthe files in existing branch while renaming.\n>\n> “the files” refers to the branch configuration and the reflog? People\n> who read the man pages might not know that the reflogs are implemented\n> as files and get tripped up. Maybe “to overwrite” could be left\n> unstated?\n\nYeah, \"overwrite the files in existing branch\" can be mislead in\nother ways, including \"in a similar way that 'checkout -f '\ncan overwrite the files with local modifications in the working tree\nwith the branch we are switching to\". We'd be better off\nnot mentioning files at all [*].\n\n ... but you can use ... to clobber an existing ``.\n\nwould be sufficient. If the verb \"clobber\" is unfamiliar to some\nreaders, \"overwrite\" is also fine. The most important part from the\nend-user's point of view is that whatever data associated with the\nname is now gone, and replaced by what was associated\nwith the name . How we stored such data associated with\neach branch is immaterial.\n\n\tSide note: Especially because we are not married to the\n\tfiles backend that stores one file per branch under\n\t.git/logs/refs/heads/ and .git/refs/heads/ directories\n\tforever. With reftable backend, there is no such files\n\tspecific to to be overwritten.\n\nAnother thing. The existence of a is not the only case\nwe fail \"git branch -m [] \", but the mention\nof this particular safety valve is to tell readers that forcing with\n`-M` is how to override the safety. We want to be absolutely clear\nthat we are not trying to exhaustively enumerate failure modes [*]\nto our readers, and I am not sure if we succeeded in the proposed\ntext.\n\n\tSide note: In other words, there are other ways the command\n\tcan fail, and `-M` may not be a way to \"fix\" these failures.\n\n> This patch also drops this part. Shouldn’t this be noted?\n>\n> « , and a reflog entry is created to remember the branch renaming.\n>\n> Right now it looks like (reads like) the reflog is moved and an entry is\n> not made about it.\n\nTrue. This was missing in my \"or something like that\" illustration\nand the patch copies without checking the original. It should be\nresurrected.\n\nThanks, both for writing and carefully reading. Removal of\n and from the OPTIONS enumaration is really\ngood, too.\n"},{"id":"488758","messageId":"dbe76244979ab5747e74837b925c71af@manjaro.org","threadId":"60928","inReplyTo":"xmqqedddo3ym.fsf@gitster.g","subject":"Re: [PATCH] branch: rework the descriptions of rename and copy operations","fromName":"Dragan Simic","fromEmail":"dsimic@manjaro.org","sentAt":"2024-02-15T21:00:08Z","receivedAt":"2024-02-15T21:00:11Z","isPatch":true,"sender":{"key":"dsimic@manjaro.org","avatar":null},"body":"Hello Junio,\n\nOn 2024-02-15 21:41, Junio C Hamano wrote:\n> \"Kristoffer Haugsbakk\" writes:\n>> (If I read this part correctly.)\n>> \n>>> --m::\n>>> ---move::\n>>> -\tMove/rename a branch, together with its config and reflog.\n>>> +-m [] ::\n>>> +--move [] ::\n>>> +\tRename an existing branch , which if not specified \n>>> defaults\n>>> +\tto the current branch, to . The configuration variables\n>> \n>> I had to read the first sentence a few times in order to understand \n>> what\n>> the “which” part was saying (which seems to come from [1] by Junio). \n>> How\n>> about letting it trail the sentence?\n>> \n>> « Rename an existing branch `` to ``, with\n>> `` defaulting to the current branch if not specified.\n> \n> Yeah, insertion of \"if not specified\" in the middle made the\n> resulting text unnecessarily hard to follow, and moving it to the\n> end is a fine fix. But I think we can just drop it (in other words,\n> we already said \"defaulting to\" and that should be sufficient).\n\nThis is what seems most readable to me:\n\n Rename an existing branch `` to ``; if left\n unspecified, `` defaults to the current branch.\n\n>>> +\tfor the branch and its reflog are also renamed \n>>> appropriately\n>>> +\tto be used with . Renaming fails if branch \n>>> +\talready exists, but you can use `-M` or `--move --force` to \n>>> overwrite\n>>> +\tthe files in existing branch while renaming.\n>> \n>> “the files” refers to the branch configuration and the reflog? People\n>> who read the man pages might not know that the reflogs are implemented\n>> as files and get tripped up. Maybe “to overwrite” could be left\n>> unstated?\n> \n> Yeah, \"overwrite the files in existing branch\" can be mislead in\n> other ways, including \"in a similar way that 'checkout -f '\n> can overwrite the files with local modifications in the working tree\n> with the branch we are switching to\". We'd be better off\n> not mentioning files at all [*].\n> \n> ... but you can use ... to clobber an existing ``.\n> \n> would be sufficient. If the verb \"clobber\" is unfamiliar to some\n> readers, \"overwrite\" is also fine. The most important part from the\n> end-user's point of view is that whatever data associated with the\n> name is now gone, and replaced by what was associated\n> with the name . How we stored such data associated with\n> each branch is immaterial.\n> \n> \tSide note: Especially because we are not married to the\n> \tfiles backend that stores one file per branch under\n> \t.git/logs/refs/heads/ and .git/refs/heads/ directories\n> \tforever. With reftable backend, there is no such files\n> \tspecific to to be overwritten.\n\nTo me, using \"clobber\" actually doesn't make it more clear. How\nabout wording it this way:\n\n Renaming fails if branch `` already exists, but `-M`\n or `--move --force` can be used to overwrite the contents of the\n existing branch `` while renaming.\n\nTo me, \"overwriting an existing branch\" means something like\n\"deleting an existing branch first, before doing anything else\".\nJust like in case of overwriting an existing file, which gets\ndeleted first, which most users are familiar with.\n\nOn the other hand, \"overwriting the contents of an existing\nbranch\", at least to me, means that the branch isn't deleted first,\nbut the new branch is \"layered\" onto it instead, overwriting some\nor all of its contents.\n\nAdditionally, \"its contents\" removes the direct link between the\nfiles and the branches, which should make the description future\nproof.\n\n> Another thing. The existence of a is not the only case\n> we fail \"git branch -m [] \", but the mention\n> of this particular safety valve is to tell readers that forcing with\n> `-M` is how to override the safety. We want to be absolutely clear\n> that we are not trying to exhaustively enumerate failure modes [*]\n> to our readers, and I am not sure if we succeeded in the proposed\n> text.\n> \n> \tSide note: In other words, there are other ways the command\n> \tcan fail, and `-M` may not be a way to \"fix\" these failures.\n> \n>> This patch also drops this part. Shouldn’t this be noted?\n>> \n>> « , and a reflog entry is created to remember the branch renaming.\n>> \n>> Right now it looks like (reads like) the reflog is moved and an entry \n>> is\n>> not made about it.\n> \n> True. This was missing in my \"or something like that\" illustration\n> and the patch copies without checking the original. It should be\n> resurrected.\n\nAlready brought this back for the v2. It was omitted in the v1 by\nan honest mistake.\n\n> Thanks, both for writing and carefully reading. Removal of\n> and from the OPTIONS enumaration is really\n> good, too.\n\nI'm glad that you're happy with the improvements so far. :)\n"},{"id":"488760","messageId":"e8fdd057-2670-4c93-b362-202a339d5f49@gmail.com","threadId":"60928","inReplyTo":"3cbc78bb5729f304b30bf37a18d1762af553aa00.1708022441.git.dsimic@manjaro.org","subject":"Re: [PATCH] branch: rework the descriptions of rename and copy operations","fromName":"Rubén Justo","fromEmail":"rjusto@gmail.com","sentAt":"2024-02-15T21:52:36Z","receivedAt":"2024-02-15T21:52:45Z","isPatch":true,"sender":{"key":"rjusto@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5685487?v=4"},"body":"On 15-feb-2024 19:42:32, Dragan Simic wrote:\n\n> Move the descriptions of the and arguments to the\n> descriptions of the branch rename and copy operations, where they naturally\n> belong.\n\nThank you Dragan for working on this.\n\nLet me chime in just to say that maybe another terms could be considered\nhere; like: \"\" and \"\" (maybe too long...) or\nso.\n\nI have no problem with the current terms, but \"\" can be a\nsensible choice here as it is already being used for other commands\nwhere, and this may help overall, the consideration: \"if ommited, the\ncurrent branch is considered\" also applies.\n\n> Also, improve the descriptions of these two branch operations and,\n> for completeness, describe the outcomes of forced operations.\n> \n> Describing the arguments together with their respective operations, instead\n> of describing them separately in a rather unfortunate attempt to squeeze more\n> meaning out of fewer words, flows much better and makes the git-branch(1)\n> man page significantly more usable.\n> \n> The subsequent improvements shall continue this approach by either dissolving\n> as many sentences from the \"Description\" section into the \"Options\" section,\n> or by having those sentences converted into some kind of more readable and\n> better flowing prose, as already discussed and outlined. [1][2]\n> \n> [1] https://lore.kernel.org/git/xmqqttmmlahf.fsf@gitster.g/T/#u\n> [2] https://lore.kernel.org/git/xmqq8r4zln08.fsf@gitster.g/T/#u\n> \n> Signed-off-by: Dragan Simic \n> ---\n> \n> Notes:\n> This patch was originally named \"branch: clarify and \n> terms further\", submitted and discussed in another thread, [3] but the nature\n> of the patch has changed, causing the patch subject to be adjusted to match.\n> \n> Consequently, this is effectively version 2 of the patch, which includes\n> detailed feedback from Kyle and Junio, who suggested moving/adding the\n> argument descriptions to their respective commands. This resulted in more\n> significant changes to the contents of the git-branch(1) man page, in an\n> attempt to make it more readable.\n> \n> [3] https://lore.kernel.org/git/e2eb777bca8ffeec42bdd684837d28dd52cfc9c3.1707136999.git.dsimic@manjaro.org/T/#u\n> \n> Documentation/git-branch.txt | 44 +++++++++++++++---------------------\n> 1 file changed, 18 insertions(+), 26 deletions(-)\n> \n> diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt\n> index 0b0844293235..370ea43c0380 100644\n> --- a/Documentation/git-branch.txt\n> +++ b/Documentation/git-branch.txt\n> @@ -72,16 +72,6 @@ the remote-tracking branch. This behavior may be changed via the global\n> overridden by using the `--track` and `--no-track` options, and\n> changed later using `git branch --set-upstream-to`.\n> \n> -With a `-m` or `-M` option, will be renamed to .\n> -If had a corresponding reflog, it is renamed to match\n> -, and a reflog entry is created to remember the branch\n> -renaming. If exists, -M must be used to force the rename\n> -to happen.\n> -\n> -The `-c` and `-C` options have the exact same semantics as `-m` and\n> -`-M`, except instead of the branch being renamed, it will be copied to a\n> -new name, along with its config and reflog.\n> -\n> With a `-d` or `-D` option, `` will be deleted. You may\n> specify more than one branch for deletion. If the branch currently\n> has a reflog then the reflog will also be deleted.\n> @@ -128,18 +118,28 @@ Note that 'git branch -f []', even with '-f',\n> refuses to change an existing branch `` that is checked out\n> in another worktree linked to the same repository.\n> \n> --m::\n> ---move::\n> -\tMove/rename a branch, together with its config and reflog.\n> +-m [] ::\n> +--move [] ::\n> +\tRename an existing branch , which if not specified defaults\n> +\tto the current branch, to . The configuration variables\n> +\tfor the branch and its reflog are also renamed appropriately\n> +\tto be used with . Renaming fails if branch \n> +\talready exists, but you can use `-M` or `--move --force` to overwrite\n> +\tthe files in existing branch while renaming.\n> \n> --M::\n> +-M [] ::\n> \tShortcut for `--move --force`.\n> \n> --c::\n> ---copy::\n> -\tCopy a branch, together with its config and reflog.\n> +-c [] ::\n> +--copy [] ::\n> +\tCopy an existing branch , which if not specified defaults\n> +\tto the current branch, to . The configuration variables\n> +\tfor the branch and its reflog are also copied appropriately\n> +\tto be used with . Copying fails if branch \n> +\talready exists, but you can use `-C` or `--copy --force` to overwrite\n> +\tthe files in existing branch while copying.\n> \n> --C::\n> +-C [] ::\n> \tShortcut for `--copy --force`.\n> \n> --color[=]::\n> @@ -311,14 +311,6 @@ superproject's \"origin/main\", but tracks the submodule's \"origin/main\".\n> \tgiven as a branch name, a commit-id, or a tag. If this\n> \toption is omitted, the current HEAD will be used instead.\n> \n> -::\n> -\tThe name of an existing branch. If this option is omitted,\n> -\tthe name of the current branch will be used instead.\n> -\n> -::\n> -\tThe new name for an existing branch. The same restrictions as for\n> -\t apply.\n> -\n> --sort=::\n> \tSort based on the key given. Prefix `-` to sort in descending\n> \torder of the value. You may use the --sort= option\n"},{"id":"488761","messageId":"xmqq8r3lnzp0.fsf@gitster.g","threadId":"60928","inReplyTo":"e8fdd057-2670-4c93-b362-202a339d5f49@gmail.com","subject":"Re: [PATCH] branch: rework the descriptions of rename and copy operations","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-02-15T22:13:31Z","receivedAt":"2024-02-15T22:13:35Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Rubén Justo writes:\n\n> On 15-feb-2024 19:42:32, Dragan Simic wrote:\n>\n>> Move the descriptions of the and arguments to the\n>> descriptions of the branch rename and copy operations, where they naturally\n>> belong.\n>\n> Thank you Dragan for working on this.\n>\n> Let me chime in just to say that maybe another terms could be considered\n> here; like: \"\" and \"\" (maybe too long...) or\n> so.\n>\n> I have no problem with the current terms, but \"\" can be a\n> sensible choice here as it is already being used for other commands\n> where, and this may help overall, the consideration: \"if ommited, the\n> current branch is considered\" also applies.\n\nActually, we should go in the opposite direction. When the use of\nnames are localized in a narrower context, they can be shortened\nwithout losing clarity. For example:\n\n -m [] ::\n\trename the branch (defaults to the current one) to\n\t.\n\nis just as clear as the same description with and\n. With the original text without any of the suggested\nchanges, and appeared very far from the\ncontext they are used in (i.e. the description for -m and -c), and\nit may have helped readers to tell that these are names of branches.\nBut if the context is clear that we are talking about \"renaming\"\nbranches, there is not as much added benefit to say \"branch\" in\nthese names as in the current text.\n\n\n"},{"id":"488762","messageId":"6caad50252bac7f75da8de7e3728a45e@manjaro.org","threadId":"60928","inReplyTo":"e8fdd057-2670-4c93-b362-202a339d5f49@gmail.com","subject":"Re: [PATCH] branch: rework the descriptions of rename and copy operations","fromName":"Dragan Simic","fromEmail":"dsimic@manjaro.org","sentAt":"2024-02-15T22:27:59Z","receivedAt":"2024-02-15T22:28:02Z","isPatch":true,"sender":{"key":"dsimic@manjaro.org","avatar":null},"body":"Hello Ruben and Junio,\n\nOn 2024-02-15 22:52, Rubén Justo wrote:\n> On 15-feb-2024 19:42:32, Dragan Simic wrote:\n> \n>> Move the descriptions of the and arguments to \n>> the\n>> descriptions of the branch rename and copy operations, where they \n>> naturally\n>> belong.\n> \n> Thank you Dragan for working on this.\n\nThank you, and everyone else, for the reviews and suggestions.\n\n> Let me chime in just to say that maybe another terms could be \n> considered\n> here; like: \"\" and \"\" (maybe too long...) \n> or\n> so.\n> \n> I have no problem with the current terms, but \"\" can be a\n> sensible choice here as it is already being used for other commands\n> where, and this may help overall, the consideration: \"if ommited, the\n> current branch is considered\" also applies.\n\nActually, I'd agree with Junio's reply that suggested using even\nshorter terms. Just like \"\" and \"\" can safely\nbe shortened to \"\" and \"\", respectively, \"\"\ncan also be shortened to \"\".\n\nIt's all about the context, which is improved by moving the descriptions\nof the arguments closer to the descriptions of the commands.\n\nThough, I'd prefer that we keep \"\" and \"\" (and\n\"\") for now, for the sake of consistency, and I'd get them\nshortened in the future patches.\n\n>> Also, improve the descriptions of these two branch operations and,\n>> for completeness, describe the outcomes of forced operations.\n>> \n>> Describing the arguments together with their respective operations, \n>> instead\n>> of describing them separately in a rather unfortunate attempt to \n>> squeeze more\n>> meaning out of fewer words, flows much better and makes the \n>> git-branch(1)\n>> man page significantly more usable.\n>> \n>> The subsequent improvements shall continue this approach by either \n>> dissolving\n>> as many sentences from the \"Description\" section into the \"Options\" \n>> section,\n>> or by having those sentences converted into some kind of more readable \n>> and\n>> better flowing prose, as already discussed and outlined. [1][2]\n>> \n>> [1] https://lore.kernel.org/git/xmqqttmmlahf.fsf@gitster.g/T/#u\n>> [2] https://lore.kernel.org/git/xmqq8r4zln08.fsf@gitster.g/T/#u\n>> \n>> Signed-off-by: Dragan Simic \n>> ---\n>> \n>> Notes:\n>> This patch was originally named \"branch: clarify and \n>> \n>> terms further\", submitted and discussed in another thread, [3] but \n>> the nature\n>> of the patch has changed, causing the patch subject to be adjusted \n>> to match.\n>> \n>> Consequently, this is effectively version 2 of the patch, which \n>> includes\n>> detailed feedback from Kyle and Junio, who suggested moving/adding \n>> the\n>> argument descriptions to their respective commands. This resulted \n>> in more\n>> significant changes to the contents of the git-branch(1) man page, \n>> in an\n>> attempt to make it more readable.\n>> \n>> [3] \n>> https://lore.kernel.org/git/e2eb777bca8ffeec42bdd684837d28dd52cfc9c3.1707136999.git.dsimic@manjaro.org/T/#u\n>> \n>> Documentation/git-branch.txt | 44 \n>> +++++++++++++++---------------------\n>> 1 file changed, 18 insertions(+), 26 deletions(-)\n>> \n>> diff --git a/Documentation/git-branch.txt \n>> b/Documentation/git-branch.txt\n>> index 0b0844293235..370ea43c0380 100644\n>> --- a/Documentation/git-branch.txt\n>> +++ b/Documentation/git-branch.txt\n>> @@ -72,16 +72,6 @@ the remote-tracking branch. This behavior may be \n>> changed via the global\n>> overridden by using the `--track` and `--no-track` options, and\n>> changed later using `git branch --set-upstream-to`.\n>> \n>> -With a `-m` or `-M` option, will be renamed to \n>> .\n>> -If had a corresponding reflog, it is renamed to match\n>> -, and a reflog entry is created to remember the branch\n>> -renaming. If exists, -M must be used to force the rename\n>> -to happen.\n>> -\n>> -The `-c` and `-C` options have the exact same semantics as `-m` and\n>> -`-M`, except instead of the branch being renamed, it will be copied \n>> to a\n>> -new name, along with its config and reflog.\n>> -\n>> With a `-d` or `-D` option, `` will be deleted. You may\n>> specify more than one branch for deletion. If the branch currently\n>> has a reflog then the reflog will also be deleted.\n>> @@ -128,18 +118,28 @@ Note that 'git branch -f \n>> []', even with '-f',\n>> refuses to change an existing branch `` that is checked \n>> out\n>> in another worktree linked to the same repository.\n>> \n>> --m::\n>> ---move::\n>> -\tMove/rename a branch, together with its config and reflog.\n>> +-m [] ::\n>> +--move [] ::\n>> +\tRename an existing branch , which if not specified \n>> defaults\n>> +\tto the current branch, to . The configuration variables\n>> +\tfor the branch and its reflog are also renamed \n>> appropriately\n>> +\tto be used with . Renaming fails if branch \n>> +\talready exists, but you can use `-M` or `--move --force` to \n>> overwrite\n>> +\tthe files in existing branch while renaming.\n>> \n>> --M::\n>> +-M [] ::\n>> \tShortcut for `--move --force`.\n>> \n>> --c::\n>> ---copy::\n>> -\tCopy a branch, together with its config and reflog.\n>> +-c [] ::\n>> +--copy [] ::\n>> +\tCopy an existing branch , which if not specified defaults\n>> +\tto the current branch, to . The configuration variables\n>> +\tfor the branch and its reflog are also copied \n>> appropriately\n>> +\tto be used with . Copying fails if branch \n>> +\talready exists, but you can use `-C` or `--copy --force` to \n>> overwrite\n>> +\tthe files in existing branch while copying.\n>> \n>> --C::\n>> +-C [] ::\n>> \tShortcut for `--copy --force`.\n>> \n>> --color[=]::\n>> @@ -311,14 +311,6 @@ superproject's \"origin/main\", but tracks the \n>> submodule's \"origin/main\".\n>> \tgiven as a branch name, a commit-id, or a tag. If this\n>> \toption is omitted, the current HEAD will be used instead.\n>> \n>> -::\n>> -\tThe name of an existing branch. If this option is omitted,\n>> -\tthe name of the current branch will be used instead.\n>> -\n>> -::\n>> -\tThe new name for an existing branch. The same restrictions as for\n>> -\t apply.\n>> -\n>> --sort=::\n>> \tSort based on the key given. Prefix `-` to sort in descending\n>> \torder of the value. You may use the --sort= option\n"},{"id":"488763","messageId":"CAO_smVioz0izmunDRyHjU_7GGz-_Om_6AVw2CZGFyb4ZF8yedg@mail.gmail.com","threadId":"60928","inReplyTo":"3cbc78bb5729f304b30bf37a18d1762af553aa00.1708022441.git.dsimic@manjaro.org","subject":"Re: [PATCH] branch: rework the descriptions of rename and copy operations","fromName":"Kyle Lippincott","fromEmail":"spectral@google.com","sentAt":"2024-02-15T22:31:31Z","receivedAt":"2024-02-15T22:31:45Z","isPatch":true,"sender":{"key":"spectral@google.com","avatar":"https://avatars.githubusercontent.com/u/6371650?v=4"},"body":"On Thu, Feb 15, 2024 at 10:43 AM Dragan Simic wrote:\n>\n> Move the descriptions of the and arguments to the\n> descriptions of the branch rename and copy operations, where they naturally\n> belong. Also, improve the descriptions of these two branch operations and,\n> for completeness, describe the outcomes of forced operations.\n>\n> Describing the arguments together with their respective operations, instead\n> of describing them separately in a rather unfortunate attempt to squeeze more\n> meaning out of fewer words, flows much better and makes the git-branch(1)\n> man page significantly more usable.\n>\n> The subsequent improvements shall continue this approach by either dissolving\n> as many sentences from the \"Description\" section into the \"Options\" section,\n> or by having those sentences converted into some kind of more readable and\n> better flowing prose, as already discussed and outlined. [1][2]\n>\n> [1] https://lore.kernel.org/git/xmqqttmmlahf.fsf@gitster.g/T/#u\n> [2] https://lore.kernel.org/git/xmqq8r4zln08.fsf@gitster.g/T/#u\n>\n> Signed-off-by: Dragan Simic \n> ---\n>\n> Notes:\n> This patch was originally named \"branch: clarify and \n> terms further\", submitted and discussed in another thread, [3] but the nature\n> of the patch has changed, causing the patch subject to be adjusted to match.\n>\n> Consequently, this is effectively version 2 of the patch, which includes\n> detailed feedback from Kyle and Junio, who suggested moving/adding the\n> argument descriptions to their respective commands. This resulted in more\n> significant changes to the contents of the git-branch(1) man page, in an\n> attempt to make it more readable.\n>\n> [3] https://lore.kernel.org/git/e2eb777bca8ffeec42bdd684837d28dd52cfc9c3.1707136999.git.dsimic@manjaro.org/T/#u\n>\n> Documentation/git-branch.txt | 44 +++++++++++++++---------------------\n> 1 file changed, 18 insertions(+), 26 deletions(-)\n\nThanks! I think this is a great improvement to this document.\n\n>\n> diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt\n> index 0b0844293235..370ea43c0380 100644\n> --- a/Documentation/git-branch.txt\n> +++ b/Documentation/git-branch.txt\n> @@ -72,16 +72,6 @@ the remote-tracking branch. This behavior may be changed via the global\n> overridden by using the `--track` and `--no-track` options, and\n> changed later using `git branch --set-upstream-to`.\n>\n> -With a `-m` or `-M` option, will be renamed to .\n> -If had a corresponding reflog, it is renamed to match\n> -, and a reflog entry is created to remember the branch\n> -renaming. If exists, -M must be used to force the rename\n> -to happen.\n> -\n> -The `-c` and `-C` options have the exact same semantics as `-m` and\n> -`-M`, except instead of the branch being renamed, it will be copied to a\n> -new name, along with its config and reflog.\n> -\n> With a `-d` or `-D` option, `` will be deleted. You may\n> specify more than one branch for deletion. If the branch currently\n> has a reflog then the reflog will also be deleted.\n> @@ -128,18 +118,28 @@ Note that 'git branch -f []', even with '-f',\n> refuses to change an existing branch `` that is checked out\n> in another worktree linked to the same repository.\n>\n> --m::\n> ---move::\n> - Move/rename a branch, together with its config and reflog.\n> +-m [] ::\n> +--move [] ::\n> + Rename an existing branch , which if not specified defaults\n> + to the current branch, to . The configuration variables\n\nVery minor nit: the prevailing style in this document appears to be to\nhave a single space after the period, but it's definitely\ninconsistent. I don't see anything in Documentation/CodingGuidelines\nsuggesting one way or the other, so don't consider this comment as\nblocking, just informational. If we want to achieve (eventual)\nconsistency, we may want to use a single space after the period now.\n\n> + for the branch and its reflog are also renamed appropriately\n> + to be used with . Renaming fails if branch \n> + already exists, but you can use `-M` or `--move --force` to overwrite\n> + the files in existing branch while renaming.\n>\n> --M::\n> +-M [] ::\n> Shortcut for `--move --force`.\n>\n> --c::\n> ---copy::\n> - Copy a branch, together with its config and reflog.\n> +-c [] ::\n> +--copy [] ::\n> + Copy an existing branch , which if not specified defaults\n> + to the current branch, to . The configuration variables\n> + for the branch and its reflog are also copied appropriately\n> + to be used with . Copying fails if branch \n> + already exists, but you can use `-C` or `--copy --force` to overwrite\n> + the files in existing branch while copying.\n>\n> --C::\n> +-C [] ::\n> Shortcut for `--copy --force`.\n>\n> --color[=]::\n> @@ -311,14 +311,6 @@ superproject's \"origin/main\", but tracks the submodule's \"origin/main\".\n> given as a branch name, a commit-id, or a tag. If this\n> option is omitted, the current HEAD will be used instead.\n>\n> -::\n> - The name of an existing branch. If this option is omitted,\n> - the name of the current branch will be used instead.\n> -\n> -::\n> - The new name for an existing branch. The same restrictions as for\n> - apply.\n> -\n> --sort=::\n> Sort based on the key given. Prefix `-` to sort in descending\n> order of the value. You may use the --sort= option\n>\n"},{"id":"488764","messageId":"e02b953f3320eff7d6ae2ecf684c8be2@manjaro.org","threadId":"60928","inReplyTo":"CAO_smVioz0izmunDRyHjU_7GGz-_Om_6AVw2CZGFyb4ZF8yedg@mail.gmail.com","subject":"Re: [PATCH] branch: rework the descriptions of rename and copy operations","fromName":"Dragan Simic","fromEmail":"dsimic@manjaro.org","sentAt":"2024-02-15T22:38:17Z","receivedAt":"2024-02-15T22:38:19Z","isPatch":true,"sender":{"key":"dsimic@manjaro.org","avatar":null},"body":"Hello Kyle,\n\nOn 2024-02-15 23:31, Kyle Lippincott wrote:\n> On Thu, Feb 15, 2024 at 10:43 AM Dragan Simic \n> wrote:\n>> \n>> Move the descriptions of the and arguments to \n>> the\n>> descriptions of the branch rename and copy operations, where they \n>> naturally\n>> belong. Also, improve the descriptions of these two branch operations \n>> and,\n>> for completeness, describe the outcomes of forced operations.\n>> \n>> Describing the arguments together with their respective operations, \n>> instead\n>> of describing them separately in a rather unfortunate attempt to \n>> squeeze more\n>> meaning out of fewer words, flows much better and makes the \n>> git-branch(1)\n>> man page significantly more usable.\n>> \n>> The subsequent improvements shall continue this approach by either \n>> dissolving\n>> as many sentences from the \"Description\" section into the \"Options\" \n>> section,\n>> or by having those sentences converted into some kind of more readable \n>> and\n>> better flowing prose, as already discussed and outlined. [1][2]\n>> \n>> [1] https://lore.kernel.org/git/xmqqttmmlahf.fsf@gitster.g/T/#u\n>> [2] https://lore.kernel.org/git/xmqq8r4zln08.fsf@gitster.g/T/#u\n>> \n>> Signed-off-by: Dragan Simic \n>> ---\n>> \n>> Notes:\n>> This patch was originally named \"branch: clarify and \n>> \n>> terms further\", submitted and discussed in another thread, [3] but \n>> the nature\n>> of the patch has changed, causing the patch subject to be adjusted \n>> to match.\n>> \n>> Consequently, this is effectively version 2 of the patch, which \n>> includes\n>> detailed feedback from Kyle and Junio, who suggested moving/adding \n>> the\n>> argument descriptions to their respective commands. This resulted \n>> in more\n>> significant changes to the contents of the git-branch(1) man page, \n>> in an\n>> attempt to make it more readable.\n>> \n>> [3] \n>> https://lore.kernel.org/git/e2eb777bca8ffeec42bdd684837d28dd52cfc9c3.1707136999.git.dsimic@manjaro.org/T/#u\n>> \n>> Documentation/git-branch.txt | 44 \n>> +++++++++++++++---------------------\n>> 1 file changed, 18 insertions(+), 26 deletions(-)\n> \n> Thanks! I think this is a great improvement to this document.\n\nThank you, I'm glad that you like it. :)\n\n>> diff --git a/Documentation/git-branch.txt \n>> b/Documentation/git-branch.txt\n>> index 0b0844293235..370ea43c0380 100644\n>> --- a/Documentation/git-branch.txt\n>> +++ b/Documentation/git-branch.txt\n>> @@ -72,16 +72,6 @@ the remote-tracking branch. This behavior may be \n>> changed via the global\n>> overridden by using the `--track` and `--no-track` options, and\n>> changed later using `git branch --set-upstream-to`.\n>> \n>> -With a `-m` or `-M` option, will be renamed to \n>> .\n>> -If had a corresponding reflog, it is renamed to match\n>> -, and a reflog entry is created to remember the branch\n>> -renaming. If exists, -M must be used to force the rename\n>> -to happen.\n>> -\n>> -The `-c` and `-C` options have the exact same semantics as `-m` and\n>> -`-M`, except instead of the branch being renamed, it will be copied \n>> to a\n>> -new name, along with its config and reflog.\n>> -\n>> With a `-d` or `-D` option, `` will be deleted. You may\n>> specify more than one branch for deletion. If the branch currently\n>> has a reflog then the reflog will also be deleted.\n>> @@ -128,18 +118,28 @@ Note that 'git branch -f \n>> []', even with '-f',\n>> refuses to change an existing branch `` that is checked \n>> out\n>> in another worktree linked to the same repository.\n>> \n>> --m::\n>> ---move::\n>> - Move/rename a branch, together with its config and reflog.\n>> +-m [] ::\n>> +--move [] ::\n>> + Rename an existing branch , which if not specified \n>> defaults\n>> + to the current branch, to . The configuration \n>> variables\n> \n> Very minor nit: the prevailing style in this document appears to be to\n> have a single space after the period, but it's definitely\n> inconsistent. I don't see anything in Documentation/CodingGuidelines\n> suggesting one way or the other, so don't consider this comment as\n> blocking, just informational. If we want to achieve (eventual)\n> consistency, we may want to use a single space after the period now.\n\nIn this case, I went with following the intersentence spacing used in\nthe surrounding text. Though, my brain and muscle memory are kind of\nhardcoded to use double spacing, which may not be as prevalent as a \nwhile\nago, but IMHO makes reading text rendered using a fixed-width font much\neasier. I can adjust if needed, of course.\n\n>> + for the branch and its reflog are also renamed \n>> appropriately\n>> + to be used with . Renaming fails if branch \n>> \n>> + already exists, but you can use `-M` or `--move --force` to \n>> overwrite\n>> + the files in existing branch while renaming.\n>> \n>> --M::\n>> +-M [] ::\n>> Shortcut for `--move --force`.\n>> \n>> --c::\n>> ---copy::\n>> - Copy a branch, together with its config and reflog.\n>> +-c [] ::\n>> +--copy [] ::\n>> + Copy an existing branch , which if not specified \n>> defaults\n>> + to the current branch, to . The configuration \n>> variables\n>> + for the branch and its reflog are also copied \n>> appropriately\n>> + to be used with . Copying fails if branch \n>> \n>> + already exists, but you can use `-C` or `--copy --force` to \n>> overwrite\n>> + the files in existing branch while copying.\n>> \n>> --C::\n>> +-C [] ::\n>> Shortcut for `--copy --force`.\n>> \n>> --color[=]::\n>> @@ -311,14 +311,6 @@ superproject's \"origin/main\", but tracks the \n>> submodule's \"origin/main\".\n>> given as a branch name, a commit-id, or a tag. If this\n>> option is omitted, the current HEAD will be used instead.\n>> \n>> -::\n>> - The name of an existing branch. If this option is omitted,\n>> - the name of the current branch will be used instead.\n>> -\n>> -::\n>> - The new name for an existing branch. The same restrictions as \n>> for\n>> - apply.\n>> -\n>> --sort=::\n>> Sort based on the key given. Prefix `-` to sort in descending\n>> order of the value. You may use the --sort= option\n>> \n"},{"id":"488765","messageId":"CAO_smVizZ6K-tSSubr7Pd95zn42GAHrgeeSQ7ZWmKdPH7gMy3w@mail.gmail.com","threadId":"60928","inReplyTo":"e02b953f3320eff7d6ae2ecf684c8be2@manjaro.org","subject":"Re: [PATCH] branch: rework the descriptions of rename and copy operations","fromName":"Kyle Lippincott","fromEmail":"spectral@google.com","sentAt":"2024-02-15T22:56:30Z","receivedAt":"2024-02-15T22:56:49Z","isPatch":true,"sender":{"key":"spectral@google.com","avatar":"https://avatars.githubusercontent.com/u/6371650?v=4"},"body":"On Thu, Feb 15, 2024 at 2:38 PM Dragan Simic wrote:\n>\n> Hello Kyle,\n>\n> On 2024-02-15 23:31, Kyle Lippincott wrote:\n> > On Thu, Feb 15, 2024 at 10:43 AM Dragan Simic \n> > wrote:\n> >>\n> >> Move the descriptions of the and arguments to\n> >> the\n> >> descriptions of the branch rename and copy operations, where they\n> >> naturally\n> >> belong. Also, improve the descriptions of these two branch operations\n> >> and,\n> >> for completeness, describe the outcomes of forced operations.\n> >>\n> >> Describing the arguments together with their respective operations,\n> >> instead\n> >> of describing them separately in a rather unfortunate attempt to\n> >> squeeze more\n> >> meaning out of fewer words, flows much better and makes the\n> >> git-branch(1)\n> >> man page significantly more usable.\n> >>\n> >> The subsequent improvements shall continue this approach by either\n> >> dissolving\n> >> as many sentences from the \"Description\" section into the \"Options\"\n> >> section,\n> >> or by having those sentences converted into some kind of more readable\n> >> and\n> >> better flowing prose, as already discussed and outlined. [1][2]\n> >>\n> >> [1] https://lore.kernel.org/git/xmqqttmmlahf.fsf@gitster.g/T/#u\n> >> [2] https://lore.kernel.org/git/xmqq8r4zln08.fsf@gitster.g/T/#u\n> >>\n> >> Signed-off-by: Dragan Simic \n> >> ---\n> >>\n> >> Notes:\n> >> This patch was originally named \"branch: clarify and\n> >> \n> >> terms further\", submitted and discussed in another thread, [3] but\n> >> the nature\n> >> of the patch has changed, causing the patch subject to be adjusted\n> >> to match.\n> >>\n> >> Consequently, this is effectively version 2 of the patch, which\n> >> includes\n> >> detailed feedback from Kyle and Junio, who suggested moving/adding\n> >> the\n> >> argument descriptions to their respective commands. This resulted\n> >> in more\n> >> significant changes to the contents of the git-branch(1) man page,\n> >> in an\n> >> attempt to make it more readable.\n> >>\n> >> [3]\n> >> https://lore.kernel.org/git/e2eb777bca8ffeec42bdd684837d28dd52cfc9c3.1707136999.git.dsimic@manjaro.org/T/#u\n> >>\n> >> Documentation/git-branch.txt | 44\n> >> +++++++++++++++---------------------\n> >> 1 file changed, 18 insertions(+), 26 deletions(-)\n> >\n> > Thanks! I think this is a great improvement to this document.\n>\n> Thank you, I'm glad that you like it. :)\n>\n> >> diff --git a/Documentation/git-branch.txt\n> >> b/Documentation/git-branch.txt\n> >> index 0b0844293235..370ea43c0380 100644\n> >> --- a/Documentation/git-branch.txt\n> >> +++ b/Documentation/git-branch.txt\n> >> @@ -72,16 +72,6 @@ the remote-tracking branch. This behavior may be\n> >> changed via the global\n> >> overridden by using the `--track` and `--no-track` options, and\n> >> changed later using `git branch --set-upstream-to`.\n> >>\n> >> -With a `-m` or `-M` option, will be renamed to\n> >> .\n> >> -If had a corresponding reflog, it is renamed to match\n> >> -, and a reflog entry is created to remember the branch\n> >> -renaming. If exists, -M must be used to force the rename\n> >> -to happen.\n> >> -\n> >> -The `-c` and `-C` options have the exact same semantics as `-m` and\n> >> -`-M`, except instead of the branch being renamed, it will be copied\n> >> to a\n> >> -new name, along with its config and reflog.\n> >> -\n> >> With a `-d` or `-D` option, `` will be deleted. You may\n> >> specify more than one branch for deletion. If the branch currently\n> >> has a reflog then the reflog will also be deleted.\n> >> @@ -128,18 +118,28 @@ Note that 'git branch -f \n> >> []', even with '-f',\n> >> refuses to change an existing branch `` that is checked\n> >> out\n> >> in another worktree linked to the same repository.\n> >>\n> >> --m::\n> >> ---move::\n> >> - Move/rename a branch, together with its config and reflog.\n> >> +-m [] ::\n> >> +--move [] ::\n> >> + Rename an existing branch , which if not specified\n> >> defaults\n> >> + to the current branch, to . The configuration\n> >> variables\n> >\n> > Very minor nit: the prevailing style in this document appears to be to\n> > have a single space after the period, but it's definitely\n> > inconsistent. I don't see anything in Documentation/CodingGuidelines\n> > suggesting one way or the other, so don't consider this comment as\n> > blocking, just informational. If we want to achieve (eventual)\n> > consistency, we may want to use a single space after the period now.\n>\n> In this case, I went with following the intersentence spacing used in\n> the surrounding text. Though, my brain and muscle memory are kind of\n> hardcoded to use double spacing, which may not be as prevalent as a\n> while\n> ago, but IMHO makes reading text rendered using a fixed-width font much\n> easier. I can adjust if needed, of course.\n\nNo need to adjust if I'm the only one mentioning it. I'm very new to\nthe project, so please don't take my style nits as any sort of\nmandate, since I'm the one that's most likely to be miscalibrated. :)\n\n>\n> >> + for the branch and its reflog are also renamed\n> >> appropriately\n> >> + to be used with . Renaming fails if branch\n> >> \n> >> + already exists, but you can use `-M` or `--move --force` to\n> >> overwrite\n> >> + the files in existing branch while renaming.\n> >>\n> >> --M::\n> >> +-M [] ::\n> >> Shortcut for `--move --force`.\n> >>\n> >> --c::\n> >> ---copy::\n> >> - Copy a branch, together with its config and reflog.\n> >> +-c [] ::\n> >> +--copy [] ::\n> >> + Copy an existing branch , which if not specified\n> >> defaults\n> >> + to the current branch, to . The configuration\n> >> variables\n> >> + for the branch and its reflog are also copied\n> >> appropriately\n> >> + to be used with . Copying fails if branch\n> >> \n> >> + already exists, but you can use `-C` or `--copy --force` to\n> >> overwrite\n> >> + the files in existing branch while copying.\n> >>\n> >> --C::\n> >> +-C [] ::\n> >> Shortcut for `--copy --force`.\n> >>\n> >> --color[=]::\n> >> @@ -311,14 +311,6 @@ superproject's \"origin/main\", but tracks the\n> >> submodule's \"origin/main\".\n> >> given as a branch name, a commit-id, or a tag. If this\n> >> option is omitted, the current HEAD will be used instead.\n> >>\n> >> -::\n> >> - The name of an existing branch. If this option is omitted,\n> >> - the name of the current branch will be used instead.\n> >> -\n> >> -::\n> >> - The new name for an existing branch. The same restrictions as\n> >> for\n> >> - apply.\n> >> -\n> >> --sort=::\n> >> Sort based on the key given. Prefix `-` to sort in descending\n> >> order of the value. You may use the --sort= option\n> >>\n"},{"id":"488766","messageId":"c1d8d7ec8639db564d09fd50ce9cf82a@manjaro.org","threadId":"60928","inReplyTo":"CAO_smVizZ6K-tSSubr7Pd95zn42GAHrgeeSQ7ZWmKdPH7gMy3w@mail.gmail.com","subject":"Re: [PATCH] branch: rework the descriptions of rename and copy operations","fromName":"Dragan Simic","fromEmail":"dsimic@manjaro.org","sentAt":"2024-02-15T23:09:31Z","receivedAt":"2024-02-15T23:09:34Z","isPatch":true,"sender":{"key":"dsimic@manjaro.org","avatar":null},"body":"On 2024-02-15 23:56, Kyle Lippincott wrote:\n> On Thu, Feb 15, 2024 at 2:38 PM Dragan Simic \n> wrote:\n>> On 2024-02-15 23:31, Kyle Lippincott wrote:\n>> > Very minor nit: the prevailing style in this document appears to be to\n>> > have a single space after the period, but it's definitely\n>> > inconsistent. I don't see anything in Documentation/CodingGuidelines\n>> > suggesting one way or the other, so don't consider this comment as\n>> > blocking, just informational. If we want to achieve (eventual)\n>> > consistency, we may want to use a single space after the period now.\n>> \n>> In this case, I went with following the intersentence spacing used in\n>> the surrounding text. Though, my brain and muscle memory are kind of\n>> hardcoded to use double spacing, which may not be as prevalent as a\n>> while\n>> ago, but IMHO makes reading text rendered using a fixed-width font \n>> much\n>> easier. I can adjust if needed, of course.\n> \n> No need to adjust if I'm the only one mentioning it. I'm very new to\n> the project, so please don't take my style nits as any sort of\n> mandate, since I'm the one that's most likely to be miscalibrated. :)\n\nBasically, when it comes to the intersentence spacing, it seems that\ndouble spacing has lost its popularity over time. It originates from\nthe old times when mechanical typewriters were used, which most people\nprobably don't even remember these days. :)\n"},{"id":"488769","messageId":"2a4de8c4-4955-4891-859c-58730a41e5af@gmail.com","threadId":"60928","inReplyTo":"xmqq8r3lnzp0.fsf@gitster.g","subject":"Re: [PATCH] branch: rework the descriptions of rename and copy operations","fromName":"Rubén Justo","fromEmail":"rjusto@gmail.com","sentAt":"2024-02-15T23:34:28Z","receivedAt":"2024-02-15T23:34:37Z","isPatch":true,"sender":{"key":"rjusto@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5685487?v=4"},"body":"On 15-feb-2024 14:13:31, Junio C Hamano wrote:\n> Rubén Justo writes:\n> \n> > On 15-feb-2024 19:42:32, Dragan Simic wrote:\n> >\n> >> Move the descriptions of the and arguments to the\n> >> descriptions of the branch rename and copy operations, where they naturally\n> >> belong.\n> >\n> > Thank you Dragan for working on this.\n> >\n> > Let me chime in just to say that maybe another terms could be considered\n> > here; like: \"\" and \"\" (maybe too long...) or\n> > so.\n> >\n> > I have no problem with the current terms, but \"\" can be a\n> > sensible choice here as it is already being used for other commands\n> > where, and this may help overall, the consideration: \"if ommited, the\n> > current branch is considered\" also applies.\n> \n> Actually, we should go in the opposite direction. When the use of\n> names are localized in a narrower context, they can be shortened\n> without losing clarity.\n\nI did not mean to have longer terms, sorry for that.\n\nI was thinking more in the synopsis:\n\n 'git branch' (--set-upstream-to= | -u ) []\n 'git branch' --unset-upstream []\n 'git branch' (-m | -M) [] \n 'git branch' (-c | -C) [] \n 'git branch' (-d | -D) [-r] ...\n 'git branch' --edit-description []\n\nTo have more uniformity in the terms, which can be beneficial to the\nuser.\n\nWe don't say that \"--edit-description\" defaults to the current branch;\nIt is assumed. Perhaps we can take advantage of that assumption in\n-m|-c too.\n\nOf course, there is no need (perhaps counterproductive) to say \"branch\"\nif the context makes it clear it is referring to a branch.\n\n> For example:\n> \n> -m [] ::\n> \trename the branch (defaults to the current one) to\n> \t.\n> \n> is just as clear as the same description with and\n> . With the original text without any of the suggested\n> changes, and appeared very far from the\n> context they are used in (i.e. the description for -m and -c), and\n> it may have helped readers to tell that these are names of branches.\n> But if the context is clear that we are talking about \"renaming\"\n> branches, there is not as much added benefit to say \"branch\" in\n> these names as in the current text.\n"},{"id":"488770","messageId":"210ae8b5-05cc-42ef-a82e-40fe7b41399b@gmail.com","threadId":"60928","inReplyTo":"6caad50252bac7f75da8de7e3728a45e@manjaro.org","subject":"Re: [PATCH] branch: rework the descriptions of rename and copy operations","fromName":"Rubén Justo","fromEmail":"rjusto@gmail.com","sentAt":"2024-02-15T23:38:33Z","receivedAt":"2024-02-15T23:38:41Z","isPatch":true,"sender":{"key":"rjusto@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5685487?v=4"},"body":"On 15-feb-2024 23:27:59, Dragan Simic wrote:\n> Hello Ruben and Junio,\n> \n> On 2024-02-15 22:52, Rubén Justo wrote:\n> > On 15-feb-2024 19:42:32, Dragan Simic wrote:\n> > \n> > > Move the descriptions of the and arguments\n> > > to the\n> > > descriptions of the branch rename and copy operations, where they\n> > > naturally\n> > > belong.\n> > \n> > Thank you Dragan for working on this.\n> \n> Thank you, and everyone else, for the reviews and suggestions.\n> \n> > Let me chime in just to say that maybe another terms could be considered\n> > here; like: \"\" and \"\" (maybe too long...) or\n> > so.\n> > \n> > I have no problem with the current terms, but \"\" can be a\n> > sensible choice here as it is already being used for other commands\n> > where, and this may help overall, the consideration: \"if ommited, the\n> > current branch is considered\" also applies.\n> \n> Actually, I'd agree with Junio's reply that suggested using even\n> shorter terms.\n\nMe too :-)\n\n> Just like \"\" and \"\" can safely\n> be shortened to \"\" and \"\", respectively, \"\"\n> can also be shortened to \"\".\n> \n> It's all about the context, which is improved by moving the descriptions\n> of the arguments closer to the descriptions of the commands.\n\nYour series is an improvement in that respect. Thank you.\n\n> \n> Though, I'd prefer that we keep \"\" and \"\" (and\n> \"\") for now, for the sake of consistency, and I'd get them\n> shortened in the future patches.\n\nNice!\n"},{"id":"488779","messageId":"ea15a49aed7b5a74cd9b1bf8a5351df9@manjaro.org","threadId":"60928","inReplyTo":"2a4de8c4-4955-4891-859c-58730a41e5af@gmail.com","subject":"Re: [PATCH] branch: rework the descriptions of rename and copy operations","fromName":"Dragan Simic","fromEmail":"dsimic@manjaro.org","sentAt":"2024-02-16T03:32:10Z","receivedAt":"2024-02-16T03:32:13Z","isPatch":true,"sender":{"key":"dsimic@manjaro.org","avatar":null},"body":"On 2024-02-16 00:34, Rubén Justo wrote:\n> On 15-feb-2024 14:13:31, Junio C Hamano wrote:\n>> Rubén Justo writes:\n>>> On 15-feb-2024 19:42:32, Dragan Simic wrote:\n>>> Let me chime in just to say that maybe another terms could be \n>>> considered\n>>> here; like: \"\" and \"\" (maybe too long...) \n>>> or\n>>> so.\n>>> \n>>> I have no problem with the current terms, but \"\" can be a\n>>> sensible choice here as it is already being used for other commands\n>>> where, and this may help overall, the consideration: \"if ommited, the\n>>> current branch is considered\" also applies.\n>> \n>> Actually, we should go in the opposite direction. When the use of\n>> names are localized in a narrower context, they can be shortened\n>> without losing clarity.\n> \n> I did not mean to have longer terms, sorry for that.\n> \n> I was thinking more in the synopsis:\n> \n> 'git branch' (--set-upstream-to= | -u ) \n> []\n> 'git branch' --unset-upstream []\n> 'git branch' (-m | -M) [] \n> 'git branch' (-c | -C) [] \n> 'git branch' (-d | -D) [-r] ...\n> 'git branch' --edit-description []\n> \n> To have more uniformity in the terms, which can be beneficial to the\n> user.\n\nHere's what I think the example from above should eventually look like:\n\n 'git branch' (--set-upstream-to= | -u ) \n[]\n 'git branch' --unset-upstream []\n 'git branch' (-m | -M) [] \n 'git branch' (-c | -C) [] \n 'git branch' (-d | -D) [-r] ...\n 'git branch' --edit-description []\n\nThough, it's something to be left for future patches, which will move\nmore argument descriptions to the respective command descriptions.\n\n> We don't say that \"--edit-description\" defaults to the current branch;\n> It is assumed. Perhaps we can take advantage of that assumption in\n> -m|-c too.\n\nWe don't say that yet, :) because the description of the command for\nediting branch descriptions is detached from the description of its\narguments. The plan is to move all of them together.\n\n> Of course, there is no need (perhaps counterproductive) to say \"branch\"\n> if the context makes it clear it is referring to a branch.\n"},{"id":"488847","messageId":"c00f6efe-d1f4-4f2c-99cc-ac7a6d93c9ff@gmail.com","threadId":"60928","inReplyTo":"ea15a49aed7b5a74cd9b1bf8a5351df9@manjaro.org","subject":"Re: [PATCH] branch: rework the descriptions of rename and copy operations","fromName":"Rubén Justo","fromEmail":"rjusto@gmail.com","sentAt":"2024-02-17T14:58:46Z","receivedAt":"2024-02-17T14:58:54Z","isPatch":true,"sender":{"key":"rjusto@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5685487?v=4"},"body":"On 16-feb-2024 04:32:10, Dragan Simic wrote:\n> On 2024-02-16 00:34, Rubén Justo wrote:\n> > On 15-feb-2024 14:13:31, Junio C Hamano wrote:\n> > > Rubén Justo writes:\n> > > > On 15-feb-2024 19:42:32, Dragan Simic wrote:\n> > > > Let me chime in just to say that maybe another terms could be\n> > > > considered\n> > > > here; like: \"\" and \"\" (maybe too\n> > > > long...) or\n> > > > so.\n> > > > \n> > > > I have no problem with the current terms, but \"\" can be a\n> > > > sensible choice here as it is already being used for other commands\n> > > > where, and this may help overall, the consideration: \"if ommited, the\n> > > > current branch is considered\" also applies.\n> > > \n> > > Actually, we should go in the opposite direction. When the use of\n> > > names are localized in a narrower context, they can be shortened\n> > > without losing clarity.\n> > \n> > I did not mean to have longer terms, sorry for that.\n> > \n> > I was thinking more in the synopsis:\n> > \n> > 'git branch' (--set-upstream-to= | -u )\n> > []\n> > 'git branch' --unset-upstream []\n> > 'git branch' (-m | -M) [] \n> > 'git branch' (-c | -C) [] \n> > 'git branch' (-d | -D) [-r] ...\n> > 'git branch' --edit-description []\n> > \n> > To have more uniformity in the terms, which can be beneficial to the\n> > user.\n> \n> Here's what I think the example from above should eventually look like:\n> \n> 'git branch' (--set-upstream-to= | -u ) []\n> 'git branch' --unset-upstream []\n\nWell, my point was not about new terms in this series, but to see if the\nidea of reusing an existing one might be of interest.\n\nI find it interesting to have common terms like \"\" \"\",\n\"\"...\n\nThis builds intuition in the user, making it easier to grasp the meaning\nof a term, which refers to a similar /thing/, regardless of being used\nin different contexts. And in turn, it can also help to better\nunderstand the context.\n\n Side note: My gut tells me that my patch 5aea3955bc (branch:\n clarify term, 2024-01-06) which was originated by a\n report [1] of a user who found the documentation confusing, would\n have been less likely to happen (the report and consequently my\n patch) if \"\" had been used instead of \"\" in\n the documentation. Not because \"\" is a better name,\n but because it is already being used in other commands with a\n clearer meaning of: \"if not specified it defaults to the current\n branch\". And because of that a user might have be able to fill the\n gaps in -m|-c. Of course this is based on my intuition, which I\n know is seriously biased.\n\n [1] https://lore.kernel.org/git/pull.1613.git.git.1701303891791.gitgitgadget@gmail.com/\n\nAnd not only can it be of help to the user, but also to developers (or\nreviewers) when documenting new commands or options; because there is\nno need to search for a, maybe new, name if there is one that is\nconsolidated.\n\nPerhaps, less names can also improve the lives of translators by making\nit easier to reuse some of the translations.\n\nAs I write, I realise that all this probably belongs to CodingGuideLines\nor similar. Or maybe it is too academic to be practical. I Dunno.\n\n> 'git branch' (-m | -M) [] \n> 'git branch' (-c | -C) [] \n> 'git branch' (-d | -D) [-r] ...\n> 'git branch' --edit-description []\n\nSo, to your proposal: it does not make things worse, and it reuses\nterms that are already used elsewhere:\n\n\t$ for a in '' '' ''; do echo $a $(git grep --no-line-number -E \"$a\" v2.44.0-rc1 -- Documentation/git-*.txt | wc -l); done\n\t 7\n\t 7\n\t 147\n\nBut based on the idea I've just described, IMHO the user might not\neasily find the similarities in with :\n\n> 'git branch' (-c | -C) [] \n> 'git branch' (-d | -D) [-r] ...\n\nAt least, not better than with and .\n\nAnd it won't be easy either with and other man pages. For\nexample we have:\n\n\t$ git grep -E 'git checkout.*(new-)?branch' Documentation/git-checkout.txt\n\tDocumentation/git-checkout.txt:'git checkout' [-q] [-f] [-m] []\n\tDocumentation/git-checkout.txt:'git checkout' [-q] [-f] [-m] --detach []\n\tDocumentation/git-checkout.txt:'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] ] []\n\tDocumentation/git-checkout.txt:'git checkout' []::\n\tDocumentation/git-checkout.txt:$ git checkout -b --track /\n\tDocumentation/git-checkout.txt:'git checkout' -b|-B []::\n\tDocumentation/git-checkout.txt:$ git checkout \n\tDocumentation/git-checkout.txt:'git checkout' --detach []::\n\tDocumentation/git-checkout.txt: \"git branch\" with \"-f\" followed by \"git checkout\" of that branch;\n\tDocumentation/git-checkout.txt:$ git checkout -b --track /\n\nOn the names chosen, the risk of bikesheeding is high and there is\nnothing wrong here, so it is way better to let you work. You have taken\nthe initiative from Junios's response to my patch, so thank you for\nthat.\n\n> Though, it's something to be left for future patches, which will move\n> more argument descriptions to the respective command descriptions.\n> \n> > We don't say that \"--edit-description\" defaults to the current branch;\n> > It is assumed. Perhaps we can take advantage of that assumption in\n> > -m|-c too.\n> \n> We don't say that yet, :)\n\nYeah, but maybe we can do it without writing it down :)\n\n> because the description of the command for\n> editing branch descriptions is detached from the description of its\n> arguments. The plan is to move all of them together.\n> \n> > Of course, there is no need (perhaps counterproductive) to say \"branch\"\n> > if the context makes it clear it is referring to a branch.\n"},{"id":"488889","messageId":"be91f3ad9305366c1385c2da4881537e@manjaro.org","threadId":"60928","inReplyTo":"c00f6efe-d1f4-4f2c-99cc-ac7a6d93c9ff@gmail.com","subject":"Re: [PATCH] branch: rework the descriptions of rename and copy operations","fromName":"Dragan Simic","fromEmail":"dsimic@manjaro.org","sentAt":"2024-02-18T20:38:54Z","receivedAt":"2024-02-18T20:39:02Z","isPatch":true,"sender":{"key":"dsimic@manjaro.org","avatar":null},"body":"Hello Ruben,\n\nOn 2024-02-17 15:58, Rubén Justo wrote:\n> On 16-feb-2024 04:32:10, Dragan Simic wrote:\n>> Here's what I think the example from above should eventually look \n>> like:\n>> \n>> 'git branch' (--set-upstream-to= | -u ) \n>> []\n>> 'git branch' --unset-upstream []\n> \n> Well, my point was not about new terms in this series, but to see if \n> the\n> idea of reusing an existing one might be of interest.\n\nGood point, ensuring such consistency would be really good.\n\n> I find it interesting to have common terms like \"\" \"\",\n> \"\"...\n\n... or \"\". :)\n\n> This builds intuition in the user, making it easier to grasp the \n> meaning\n> of a term, which refers to a similar /thing/, regardless of being used\n> in different contexts. And in turn, it can also help to better\n> understand the context.\n\nAgreed, consistency is good.\n\n> Side note: My gut tells me that my patch 5aea3955bc (branch:\n> clarify term, 2024-01-06) which was originated by a\n> report [1] of a user who found the documentation confusing, would\n> have been less likely to happen (the report and consequently my\n> patch) if \"\" had been used instead of \"\" in\n> the documentation. Not because \"\" is a better name,\n> but because it is already being used in other commands with a\n> clearer meaning of: \"if not specified it defaults to the current\n> branch\". And because of that a user might have be able to fill \n> the\n> gaps in -m|-c. Of course this is based on my intuition, which I\n> know is seriously biased.\n> \n> [1] \n> https://lore.kernel.org/git/pull.1613.git.git.1701303891791.gitgitgadget@gmail.com/\n\nAfter thinking a bit more about the whole thing, I think that using\n\"\" instead of \"\" or \"\" would be our best\nchoice. It would be simple, direct and clear.\n\nRegarding the branch copy and rename operations and their argument\nnames, perhaps the following would be a good choice:\n\n --copy [] \n --move [] \n\nIt would clearly reflect the nature of the performed operations, while\nstill using \"\" consistently, this time to refer to the source\nbranch. Using \"\" to select the destination name should\nbe pretty much self-descriptive, if you agree.\n\nOf course, I'll get back to this later in this message.\n\n> And not only can it be of help to the user, but also to developers (or\n> reviewers) when documenting new commands or options; because there is\n> no need to search for a, maybe new, name if there is one that is\n> consolidated.\n> \n> Perhaps, less names can also improve the lives of translators by making\n> it easier to reuse some of the translations.\n\nPerhaps. That should be another example of the long-term benefits\nachieved through improved consistency.\n\n>> 'git branch' (-m | -M) [] \n>> 'git branch' (-c | -C) [] \n>> 'git branch' (-d | -D) [-r] ...\n>> 'git branch' --edit-description []\n> \n> So, to your proposal: it does not make things worse, and it reuses\n> terms that are already used elsewhere:\n> \n> \t$ for a in '' '' ''; do echo $a $(git grep\n> --no-line-number -E \"$a\" v2.44.0-rc1 -- Documentation/git-*.txt | wc\n> -l); done\n> \t 7\n> \t 7\n> \t 147\n> \n> But based on the idea I've just described, IMHO the user might not\n> easily find the similarities in with :\n\nI agree after thinking about the whole thing a bit more.\n\n> And it won't be easy either with and other man pages. For\n> example we have:\n> \n> \t$ git grep -E 'git checkout.*(new-)?branch' \n> Documentation/git-checkout.txt\n> \tDocumentation/git-checkout.txt:'git checkout' [-q] [-f] [-m] \n> []\n> \tDocumentation/git-checkout.txt:'git checkout' [-q] [-f] [-m] --detach\n> []\n> \tDocumentation/git-checkout.txt:'git checkout' [-q] [-f] [-m]\n> [[-b|-B|--orphan] ] []\n> \tDocumentation/git-checkout.txt:'git checkout' []::\n> \tDocumentation/git-checkout.txt:$ git checkout -b --track\n> /\n> \tDocumentation/git-checkout.txt:'git checkout' -b|-B \n> []::\n> \tDocumentation/git-checkout.txt:$ git checkout \n> \tDocumentation/git-checkout.txt:'git checkout' --detach []::\n> \tDocumentation/git-checkout.txt: \"git branch\" with \"-f\" followed\n> by \"git checkout\" of that branch;\n> \tDocumentation/git-checkout.txt:$ git checkout -b --track\n> /\n\nI'd say this solidifies \"\" as, hopefully, our best choice,\nas already proposed above.\n\n> On the names chosen, the risk of bikesheeding is high and there is\n> nothing wrong here, so it is way better to let you work. You have \n> taken\n> the initiative from Junios's response to my patch, so thank you for\n> that.\n\nI hope we'll eventually produce a great git-branch(1) man page together.\nAfter that's completed, I have some more plans for improving git-branch,\nby introducing some additional operations.\n\n>> > We don't say that \"--edit-description\" defaults to the current branch;\n>> > It is assumed. Perhaps we can take advantage of that assumption in\n>> > -m|-c too.\n>> \n>> We don't say that yet, :)\n> \n> Yeah, but maybe we can do it without writing it down :)\n\nMaybe, :) but again, spending a few additional words to describe that\nmight actually be beneficial. We'll see how it goes.\n"},{"id":"488922","messageId":"xmqq8r3g8caz.fsf@gitster.g","threadId":"60928","inReplyTo":"be91f3ad9305366c1385c2da4881537e@manjaro.org","subject":"Re: [PATCH] branch: rework the descriptions of rename and copy operations","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-02-19T19:49:08Z","receivedAt":"2024-02-19T19:49:14Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Dragan Simic writes:\n\n> Regarding the branch copy and rename operations and their argument\n> names, perhaps the following would be a good choice:\n>\n> --copy [] \n> --move [] \n>\n> It would clearly reflect the nature of the performed operations, while\n> still using \"\" consistently, this time to refer to the source\n> branch. Using \"\" to select the destination name should\n> be pretty much self-descriptive, if you agree.\n\nAwful. While I was skimming the messages without reading the\nSubject line (hence without realizing that this is about improving\nthe existing documentation and not adding new features), I thought\nthat these two are about moving branch to a remote repository that\nis named with .\n\nMy advice would be to stick to vs that contrasts well.\n\nThanks.\n\n"},{"id":"488923","messageId":"35738a93f5cbace5b3235ce614b7afbf@manjaro.org","threadId":"60928","inReplyTo":"xmqq8r3g8caz.fsf@gitster.g","subject":"Re: [PATCH] branch: rework the descriptions of rename and copy operations","fromName":"Dragan Simic","fromEmail":"dsimic@manjaro.org","sentAt":"2024-02-19T19:55:33Z","receivedAt":"2024-02-19T19:55:35Z","isPatch":true,"sender":{"key":"dsimic@manjaro.org","avatar":null},"body":"Hello Junio,\n\nOn 2024-02-19 20:49, Junio C Hamano wrote:\n> Dragan Simic writes:\n> \n>> Regarding the branch copy and rename operations and their argument\n>> names, perhaps the following would be a good choice:\n>> \n>> --copy [] \n>> --move [] \n>> \n>> It would clearly reflect the nature of the performed operations, while\n>> still using \"\" consistently, this time to refer to the source\n>> branch. Using \"\" to select the destination name should\n>> be pretty much self-descriptive, if you agree.\n> \n> Awful. While I was skimming the messages without reading the\n> Subject line (hence without realizing that this is about improving\n> the existing documentation and not adding new features), I thought\n> that these two are about moving branch to a remote repository that\n> is named with .\n> \n> My advice would be to stick to vs that contrasts well.\n\nI appreciate the directness and honesty. How about using \"\"\nand \"\" instead, which, although more wordy, would be more\nconsistent with \"\" that's used in a number of other places?\nSuch consistency should make the users recognize the arguments better\nat first glance.\n"},{"id":"489005","messageId":"xmqqttm3ouxy.fsf@gitster.g","threadId":"60928","inReplyTo":"35738a93f5cbace5b3235ce614b7afbf@manjaro.org","subject":"Re: [PATCH] branch: rework the descriptions of rename and copy operations","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-02-20T18:24:25Z","receivedAt":"2024-02-20T18:24:28Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Dragan Simic writes:\n\n>> My advice would be to stick to vs that contrasts well.\n>\n> I appreciate the directness and honesty. How about using \"\"\n> and \"\" instead, which, although more wordy, would be more\n> consistent with \"\" that's used in a number of other places?\n\nI have slight aversion to non-words like \"oldbranch\" (not\n\"old-branch\"), but not that much.\n\nQuite honestly, in a document whose primary topic is \"branch\", I\ndoubt that repeating \"branch\" all over the place would be the\nconsistency we should be aiming for in the first place, when it is\nclear from the context that we are talking about branches.\n\nThe updates we are making to Documentation/git-branch.txt that (1)\nslims wordy description of different modes in the DESCRIPTION\nsection, (2) make option description of \"-m\" mention what\nargument(s) the option takes, and (3) rmove standalone \nand description are all about making the necessary piece\nof information easier to find in one place (namely, the option\ndescription where \"-m [] []\"\nis described) without having to jump around all over in the\ndocumentation, so in that sense, I would think the way to go is to\naim for brevity that takes advantage of the local context.\n\n"},{"id":"489013","messageId":"16c1f883-881f-4f8c-95b2-22fb4825b733@gmail.com","threadId":"60928","inReplyTo":"xmqqttm3ouxy.fsf@gitster.g","subject":"Re: [PATCH] branch: rework the descriptions of rename and copy operations","fromName":"Rubén Justo","fromEmail":"rjusto@gmail.com","sentAt":"2024-02-20T19:12:16Z","receivedAt":"2024-02-20T19:12:20Z","isPatch":true,"sender":{"key":"rjusto@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5685487?v=4"},"body":"On 20-feb-2024 10:24:25, Junio C Hamano wrote:\n\n> I have slight aversion to non-words like \"oldbranch\" (not\n> \"old-branch\"), but not that much.\n\nI also have problems with . What's the reference in \"old\"?\n\nPrior to the restructuring of the whole file, we should probably do:\n\n---- >8 --------- >8 --------- >8 --------- >8 ------\nSubject: [PATCH] branch: adjust documentation\n\nAdjust the terms we use in Documentation/git-branch.txt to what\nwe say in CodingGuideLines:\n\n\tIf a placeholder has multiple words, they are separated by dashes:\n\t \n\t --template=\n\nBest viewed with --word-diff.\n\nSigned-off-by: Rubén Justo \n---\n Documentation/git-branch.txt | 57 +++++++++++++++++-------------------\n 1 file changed, 27 insertions(+), 30 deletions(-)\n\ndiff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt\nindex 0b08442932..d834d89a7f 100644\n--- a/Documentation/git-branch.txt\n+++ b/Documentation/git-branch.txt\n@@ -17,13 +17,13 @@ SYNOPSIS\n \t[(-r | --remotes) | (-a | --all)]\n \t[--list] [...]\n 'git branch' [--track[=(direct|inherit)] | --no-track] [-f]\n-\t[--recurse-submodules] []\n-'git branch' (--set-upstream-to= | -u ) []\n-'git branch' --unset-upstream []\n-'git branch' (-m | -M) [] \n-'git branch' (-c | -C) [] \n-'git branch' (-d | -D) [-r] ...\n-'git branch' --edit-description []\n+\t[--recurse-submodules] []\n+'git branch' (--set-upstream-to= | -u ) []\n+'git branch' --unset-upstream []\n+'git branch' (-m | -M) [] \n+'git branch' (-c | -C) [] \n+'git branch' (-d | -D) [-r] ...\n+'git branch' --edit-description []\n \n DESCRIPTION\n -----------\n@@ -53,7 +53,7 @@ branches not merged into the named commit will be listed. If the \n argument is missing it defaults to `HEAD` (i.e. the tip of the current\n branch).\n \n-The command's second form creates a new branch head named \n+The command's second form creates a new branch head named \n which points to the current `HEAD`, or if given. As a\n special case, for , you may use `\"A...B\"` as a shortcut for\n the merge base of `A` and `B` if there is exactly one merge base. You\n@@ -61,7 +61,7 @@ can leave out at most one of `A` and `B`, in which case it defaults to\n `HEAD`.\n \n Note that this will create the new branch, but it will not switch the\n-working tree to it; use \"git switch \" to switch to the\n+working tree to it; use \"git switch\" to switch to the\n new branch.\n \n When a local branch is started off a remote-tracking branch, Git sets up the\n@@ -72,17 +72,17 @@ the remote-tracking branch. This behavior may be changed via the global\n overridden by using the `--track` and `--no-track` options, and\n changed later using `git branch --set-upstream-to`.\n \n-With a `-m` or `-M` option, will be renamed to .\n-If had a corresponding reflog, it is renamed to match\n-, and a reflog entry is created to remember the branch\n-renaming. If exists, -M must be used to force the rename\n+With a `-m` or `-M` option, will be renamed to .\n+If had a corresponding reflog, it is renamed to match\n+, and a reflog entry is created to remember the branch\n+renaming. If exists, -M must be used to force the rename\n to happen.\n \n The `-c` and `-C` options have the exact same semantics as `-m` and\n `-M`, except instead of the branch being renamed, it will be copied to a\n new name, along with its config and reflog.\n \n-With a `-d` or `-D` option, `` will be deleted. You may\n+With a `-d` or `-D` option, `` will be deleted. You may\n specify more than one branch for deletion. If the branch currently\n has a reflog then the reflog will also be deleted.\n \n@@ -107,7 +107,7 @@ OPTIONS\n --create-reflog::\n \tCreate the branch's reflog. This activates recording of\n \tall changes made to the branch ref, enabling use of date\n-\tbased sha1 expressions such as \"@\\{yesterday}\".\n+\tbased sha1 expressions such as \"@\\{yesterday}\".\n \tNote that in non-bare repositories, reflogs are usually\n \tenabled by default by the `core.logAllRefUpdates` config option.\n \tThe negated form `--no-create-reflog` only overrides an earlier\n@@ -116,7 +116,7 @@ OPTIONS\n \n -f::\n --force::\n-\tReset to , even if exists\n+\tReset to , even if exists\n \talready. Without `-f`, 'git branch' refuses to change an existing branch.\n \tIn combination with `-d` (or `--delete`), allow deleting the\n \tbranch irrespective of its merged status, or whether it even\n@@ -124,8 +124,8 @@ OPTIONS\n \t`-m` (or `--move`), allow renaming the branch even if the new\n \tbranch name already exists, the same applies for `-c` (or `--copy`).\n +\n-Note that 'git branch -f []', even with '-f',\n-refuses to change an existing branch `` that is checked out\n+Note that 'git branch -f []', even with '-f',\n+refuses to change an existing branch `` that is checked out\n in another worktree linked to the same repository.\n \n -m::\n@@ -255,7 +255,7 @@ how the `branch..remote` and `branch..merge` options are used.\n \tlinkgit:git-config[1]. Currently, only branch creation is\n \tsupported.\n +\n-When used in branch creation, a new branch will be created\n+When used in branch creation, a new branch will be created\n in the superproject and all of the submodules in the superproject's\n . In submodules, the branch will point to the submodule\n commit in the superproject's but the branch's tracking\n@@ -270,12 +270,12 @@ superproject's \"origin/main\", but tracks the submodule's \"origin/main\".\n \n -u ::\n --set-upstream-to=::\n-\tSet up 's tracking information so is\n-\tconsidered 's upstream branch. If no \n+\tSet up 's tracking information so is\n+\tconsidered 's upstream branch. If no \n \tis specified, then it defaults to the current branch.\n \n --unset-upstream::\n-\tRemove the upstream information for . If no branch\n+\tRemove the upstream information for . If no branch\n \tis specified it defaults to the current branch.\n \n --edit-description::\n@@ -300,24 +300,21 @@ superproject's \"origin/main\", but tracks the submodule's \"origin/main\".\n \tOnly list branches whose tips are not reachable from the\n \tspecified commit (HEAD if not specified). Implies `--list`.\n \n-::\n+::\n \tThe name of the branch to create or delete.\n \tThe new branch name must pass all checks defined by\n \tlinkgit:git-check-ref-format[1]. Some of these checks\n \tmay restrict the characters allowed in a branch name.\n+\tIf ommited, the current branch will be used instead.\n \n ::\n \tThe new branch head will point to this commit. It may be\n \tgiven as a branch name, a commit-id, or a tag. If this\n \toption is omitted, the current HEAD will be used instead.\n \n-::\n-\tThe name of an existing branch. If this option is omitted,\n-\tthe name of the current branch will be used instead.\n-\n-::\n-\tThe new name for an existing branch. The same restrictions as for\n-\t apply.\n+::\n+\tThe name for new branch. The same restrictions as for\n+\t apply.\n \n --sort=::\n \tSort based on the key given. Prefix `-` to sort in descending\n-- \n2.44.0.rc2\n"},{"id":"489014","messageId":"ad20099a-918d-4c37-8d5c-20c3f491728a@gmail.com","threadId":"60928","inReplyTo":"be91f3ad9305366c1385c2da4881537e@manjaro.org","subject":"Re: [PATCH] branch: rework the descriptions of rename and copy operations","fromName":"Rubén Justo","fromEmail":"rjusto@gmail.com","sentAt":"2024-02-20T19:14:56Z","receivedAt":"2024-02-20T19:14:59Z","isPatch":true,"sender":{"key":"rjusto@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5685487?v=4"},"body":"On 18-feb-2024 21:38:54, Dragan Simic wrote:\n\n> Regarding the branch copy and rename operations and their argument\n> names, perhaps the following would be a good choice:\n> \n> --copy [] \n> --move [] \n> \n> It would clearly reflect the nature of the performed operations, while\n> still using \"\" consistently, this time to refer to the source\n> branch. Using \"\" to select the destination name should\n> be pretty much self-descriptive, if you agree.\n\nSorry, but I don't. Actually, I don't see the logic with .\n\nI appreciate your efforts to provide consistency, but the current ones\nseem better options to me: either and , or the\nshortened ones: and .\n\nThanks.\n"},{"id":"489017","messageId":"95b86d73f934b486171c7e169080f43e@manjaro.org","threadId":"60928","inReplyTo":"xmqqttm3ouxy.fsf@gitster.g","subject":"Re: [PATCH] branch: rework the descriptions of rename and copy operations","fromName":"Dragan Simic","fromEmail":"dsimic@manjaro.org","sentAt":"2024-02-20T19:32:23Z","receivedAt":"2024-02-20T19:32:26Z","isPatch":true,"sender":{"key":"dsimic@manjaro.org","avatar":null},"body":"On 2024-02-20 19:24, Junio C Hamano wrote:\n> Dragan Simic writes:\n> \n>>> My advice would be to stick to vs that contrasts well.\n>> \n>> I appreciate the directness and honesty. How about using \n>> \"\"\n>> and \"\" instead, which, although more wordy, would be more\n>> consistent with \"\" that's used in a number of other places?\n> \n> I have slight aversion to non-words like \"oldbranch\" (not\n> \"old-branch\"), but not that much.\n> \n> Quite honestly, in a document whose primary topic is \"branch\", I\n> doubt that repeating \"branch\" all over the place would be the\n> consistency we should be aiming for in the first place, when it is\n> clear from the context that we are talking about branches.\n> \n> The updates we are making to Documentation/git-branch.txt that (1)\n> slims wordy description of different modes in the DESCRIPTION\n> section, (2) make option description of \"-m\" mention what\n> argument(s) the option takes, and (3) rmove standalone \n> and description are all about making the necessary piece\n> of information easier to find in one place (namely, the option\n> description where \"-m [] []\"\n> is described) without having to jump around all over in the\n> documentation, so in that sense, I would think the way to go is to\n> aim for brevity that takes advantage of the local context.\n\nIt's hard not to agree with the way you laid this out. :)\n\nIn a nutshell, the way I see it, using \"\" and \"\" is also fine.\nIt's also fine with me to use \"\" instead of \"\"; in fact,\nif we go with \"\" and \"\", we should go with \"\", too.\n"},{"id":"489020","messageId":"59ff7c3caec40bf96795ab140d57afbd@manjaro.org","threadId":"60928","inReplyTo":"16c1f883-881f-4f8c-95b2-22fb4825b733@gmail.com","subject":"Re: [PATCH] branch: rework the descriptions of rename and copy operations","fromName":"Dragan Simic","fromEmail":"dsimic@manjaro.org","sentAt":"2024-02-20T19:49:33Z","receivedAt":"2024-02-20T19:49:36Z","isPatch":true,"sender":{"key":"dsimic@manjaro.org","avatar":null},"body":"On 2024-02-20 20:12, Rubén Justo wrote:\n> On 20-feb-2024 10:24:25, Junio C Hamano wrote:\n> \n>> I have slight aversion to non-words like \"oldbranch\" (not\n>> \"old-branch\"), but not that much.\n> \n> I also have problems with . What's the reference in \"old\"?\n> \n> Prior to the restructuring of the whole file, we should probably do:\n\nFWIW, I'm perfectly fine with having your patch, available below,\napplied right now. To me, it would provide a true improvement.\n\n> ---- >8 --------- >8 --------- >8 --------- >8 ------\n> Subject: [PATCH] branch: adjust documentation\n> \n> Adjust the terms we use in Documentation/git-branch.txt to what\n> we say in CodingGuideLines:\n> \n> \tIf a placeholder has multiple words, they are separated by dashes:\n> \t \n> \t --template=\n> \n> Best viewed with --word-diff.\n> \n> Signed-off-by: Rubén Justo \n> ---\n> Documentation/git-branch.txt | 57 +++++++++++++++++-------------------\n> 1 file changed, 27 insertions(+), 30 deletions(-)\n> \n> diff --git a/Documentation/git-branch.txt \n> b/Documentation/git-branch.txt\n> index 0b08442932..d834d89a7f 100644\n> --- a/Documentation/git-branch.txt\n> +++ b/Documentation/git-branch.txt\n> @@ -17,13 +17,13 @@ SYNOPSIS\n> \t[(-r | --remotes) | (-a | --all)]\n> \t[--list] [...]\n> 'git branch' [--track[=(direct|inherit)] | --no-track] [-f]\n> -\t[--recurse-submodules] []\n> -'git branch' (--set-upstream-to= | -u ) \n> []\n> -'git branch' --unset-upstream []\n> -'git branch' (-m | -M) [] \n> -'git branch' (-c | -C) [] \n> -'git branch' (-d | -D) [-r] ...\n> -'git branch' --edit-description []\n> +\t[--recurse-submodules] []\n> +'git branch' (--set-upstream-to= | -u ) []\n> +'git branch' --unset-upstream []\n> +'git branch' (-m | -M) [] \n> +'git branch' (-c | -C) [] \n> +'git branch' (-d | -D) [-r] ...\n> +'git branch' --edit-description []\n> \n> DESCRIPTION\n> -----------\n> @@ -53,7 +53,7 @@ branches not merged into the named commit will be\n> listed. If the \n> argument is missing it defaults to `HEAD` (i.e. the tip of the current\n> branch).\n> \n> -The command's second form creates a new branch head named \n> +The command's second form creates a new branch head named \n> which points to the current `HEAD`, or if given. As a\n> special case, for , you may use `\"A...B\"` as a shortcut \n> for\n> the merge base of `A` and `B` if there is exactly one merge base. You\n> @@ -61,7 +61,7 @@ can leave out at most one of `A` and `B`, in which\n> case it defaults to\n> `HEAD`.\n> \n> Note that this will create the new branch, but it will not switch the\n> -working tree to it; use \"git switch \" to switch to the\n> +working tree to it; use \"git switch\" to switch to the\n> new branch.\n> \n> When a local branch is started off a remote-tracking branch, Git sets \n> up the\n> @@ -72,17 +72,17 @@ the remote-tracking branch. This behavior may be\n> changed via the global\n> overridden by using the `--track` and `--no-track` options, and\n> changed later using `git branch --set-upstream-to`.\n> \n> -With a `-m` or `-M` option, will be renamed to \n> .\n> -If had a corresponding reflog, it is renamed to match\n> -, and a reflog entry is created to remember the branch\n> -renaming. If exists, -M must be used to force the rename\n> +With a `-m` or `-M` option, will be renamed to .\n> +If had a corresponding reflog, it is renamed to match\n> +, and a reflog entry is created to remember the branch\n> +renaming. If exists, -M must be used to force the rename\n> to happen.\n> \n> The `-c` and `-C` options have the exact same semantics as `-m` and\n> `-M`, except instead of the branch being renamed, it will be copied to \n> a\n> new name, along with its config and reflog.\n> \n> -With a `-d` or `-D` option, `` will be deleted. You may\n> +With a `-d` or `-D` option, `` will be deleted. You may\n> specify more than one branch for deletion. If the branch currently\n> has a reflog then the reflog will also be deleted.\n> \n> @@ -107,7 +107,7 @@ OPTIONS\n> --create-reflog::\n> \tCreate the branch's reflog. This activates recording of\n> \tall changes made to the branch ref, enabling use of date\n> -\tbased sha1 expressions such as \"@\\{yesterday}\".\n> +\tbased sha1 expressions such as \"@\\{yesterday}\".\n> \tNote that in non-bare repositories, reflogs are usually\n> \tenabled by default by the `core.logAllRefUpdates` config option.\n> \tThe negated form `--no-create-reflog` only overrides an earlier\n> @@ -116,7 +116,7 @@ OPTIONS\n> \n> -f::\n> --force::\n> -\tReset to , even if exists\n> +\tReset to , even if exists\n> \talready. Without `-f`, 'git branch' refuses to change an existing \n> branch.\n> \tIn combination with `-d` (or `--delete`), allow deleting the\n> \tbranch irrespective of its merged status, or whether it even\n> @@ -124,8 +124,8 @@ OPTIONS\n> \t`-m` (or `--move`), allow renaming the branch even if the new\n> \tbranch name already exists, the same applies for `-c` (or `--copy`).\n> +\n> -Note that 'git branch -f []', even with \n> '-f',\n> -refuses to change an existing branch `` that is checked \n> out\n> +Note that 'git branch -f []', even with '-f',\n> +refuses to change an existing branch `` that is checked out\n> in another worktree linked to the same repository.\n> \n> -m::\n> @@ -255,7 +255,7 @@ how the `branch..remote` and\n> `branch..merge` options are used.\n> \tlinkgit:git-config[1]. Currently, only branch creation is\n> \tsupported.\n> +\n> -When used in branch creation, a new branch will be \n> created\n> +When used in branch creation, a new branch will be created\n> in the superproject and all of the submodules in the superproject's\n> . In submodules, the branch will point to the submodule\n> commit in the superproject's but the branch's tracking\n> @@ -270,12 +270,12 @@ superproject's \"origin/main\", but tracks the\n> submodule's \"origin/main\".\n> \n> -u ::\n> --set-upstream-to=::\n> -\tSet up 's tracking information so is\n> -\tconsidered 's upstream branch. If no \n> +\tSet up 's tracking information so is\n> +\tconsidered 's upstream branch. If no \n> \tis specified, then it defaults to the current branch.\n> \n> --unset-upstream::\n> -\tRemove the upstream information for . If no branch\n> +\tRemove the upstream information for . If no branch\n> \tis specified it defaults to the current branch.\n> \n> --edit-description::\n> @@ -300,24 +300,21 @@ superproject's \"origin/main\", but tracks the\n> submodule's \"origin/main\".\n> \tOnly list branches whose tips are not reachable from the\n> \tspecified commit (HEAD if not specified). Implies `--list`.\n> \n> -::\n> +::\n> \tThe name of the branch to create or delete.\n> \tThe new branch name must pass all checks defined by\n> \tlinkgit:git-check-ref-format[1]. Some of these checks\n> \tmay restrict the characters allowed in a branch name.\n> +\tIf ommited, the current branch will be used instead.\n> \n> ::\n> \tThe new branch head will point to this commit. It may be\n> \tgiven as a branch name, a commit-id, or a tag. If this\n> \toption is omitted, the current HEAD will be used instead.\n> \n> -::\n> -\tThe name of an existing branch. If this option is omitted,\n> -\tthe name of the current branch will be used instead.\n> -\n> -::\n> -\tThe new name for an existing branch. The same restrictions as for\n> -\t apply.\n> +::\n> +\tThe name for new branch. The same restrictions as for\n> +\t apply.\n> \n> --sort=::\n> \tSort based on the key given. Prefix `-` to sort in descending\n"},{"id":"489021","messageId":"164b9780e82b3c677ad97fc8545353e7@manjaro.org","threadId":"60928","inReplyTo":"ad20099a-918d-4c37-8d5c-20c3f491728a@gmail.com","subject":"Re: [PATCH] branch: rework the descriptions of rename and copy operations","fromName":"Dragan Simic","fromEmail":"dsimic@manjaro.org","sentAt":"2024-02-20T19:56:53Z","receivedAt":"2024-02-20T19:56:55Z","isPatch":true,"sender":{"key":"dsimic@manjaro.org","avatar":null},"body":"On 2024-02-20 20:14, Rubén Justo wrote:\n> On 18-feb-2024 21:38:54, Dragan Simic wrote:\n> \n>> Regarding the branch copy and rename operations and their argument\n>> names, perhaps the following would be a good choice:\n>> \n>> --copy [] \n>> --move [] \n>> \n>> It would clearly reflect the nature of the performed operations, while\n>> still using \"\" consistently, this time to refer to the source\n>> branch. Using \"\" to select the destination name should\n>> be pretty much self-descriptive, if you agree.\n> \n> Sorry, but I don't. Actually, I don't see the logic with \n> .\n\nNo worries, I appreciate the directness.\n\n> I appreciate your efforts to provide consistency, but the current ones\n> seem better options to me: either and , or the\n> shortened ones: and .\n\nAs I wrote a bit earlier, while replying to Junio, using \"\" and\n\"\" (together with \"\") is fine with me.\n\nThough, using \"\" and \"\" is also a very good option,\nwhich would additionally avoid introducing \"\" to replace \n\"\",\nwhich I find highly beneficial, because it would provide consistency\nwith the rest of the documentation.\n"},{"id":"489024","messageId":"96f1afa6-f4ac-4593-9bf4-72dafe3cab85@gmail.com","threadId":"60928","inReplyTo":"16c1f883-881f-4f8c-95b2-22fb4825b733@gmail.com","subject":"[PATCH] branch: adjust documentation","fromName":"Rubén Justo","fromEmail":"rjusto@gmail.com","sentAt":"2024-02-20T20:25:56Z","receivedAt":"2024-02-20T20:25:59Z","isPatch":true,"sender":{"key":"rjusto@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5685487?v=4"},"body":"Adjust the placeholders we use in Documentation/git-branch.txt to what\nwe say in CodingGuideLines:\n\n\tIf a placeholder has multiple words, they are separated by dashes:\n\t \n\t --template=\n\nBest viewed with --word-diff.\n\nSigned-off-by: Rubén Justo \n---\n\n Documentation/git-branch.txt | 54 +++++++++++++++++-------------------\n 1 file changed, 25 insertions(+), 29 deletions(-)\n\ndiff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt\nindex 0b08442932..489507e25f 100644\n--- a/Documentation/git-branch.txt\n+++ b/Documentation/git-branch.txt\n@@ -17,13 +17,13 @@ SYNOPSIS\n \t[(-r | --remotes) | (-a | --all)]\n \t[--list] [...]\n 'git branch' [--track[=(direct|inherit)] | --no-track] [-f]\n-\t[--recurse-submodules] []\n-'git branch' (--set-upstream-to= | -u ) []\n-'git branch' --unset-upstream []\n-'git branch' (-m | -M) [] \n-'git branch' (-c | -C) [] \n-'git branch' (-d | -D) [-r] ...\n-'git branch' --edit-description []\n+\t[--recurse-submodules] []\n+'git branch' (--set-upstream-to= | -u ) []\n+'git branch' --unset-upstream []\n+'git branch' (-m | -M) [] \n+'git branch' (-c | -C) [] \n+'git branch' (-d | -D) [-r] ...\n+'git branch' --edit-description []\n \n DESCRIPTION\n -----------\n@@ -53,7 +53,7 @@ branches not merged into the named commit will be listed. If the \n argument is missing it defaults to `HEAD` (i.e. the tip of the current\n branch).\n \n-The command's second form creates a new branch head named \n+The command's second form creates a new branch head named \n which points to the current `HEAD`, or if given. As a\n special case, for , you may use `\"A...B\"` as a shortcut for\n the merge base of `A` and `B` if there is exactly one merge base. You\n@@ -61,7 +61,7 @@ can leave out at most one of `A` and `B`, in which case it defaults to\n `HEAD`.\n \n Note that this will create the new branch, but it will not switch the\n-working tree to it; use \"git switch \" to switch to the\n+working tree to it; use \"git switch \" to switch to the\n new branch.\n \n When a local branch is started off a remote-tracking branch, Git sets up the\n@@ -72,17 +72,17 @@ the remote-tracking branch. This behavior may be changed via the global\n overridden by using the `--track` and `--no-track` options, and\n changed later using `git branch --set-upstream-to`.\n \n-With a `-m` or `-M` option, will be renamed to .\n-If had a corresponding reflog, it is renamed to match\n-, and a reflog entry is created to remember the branch\n-renaming. If exists, -M must be used to force the rename\n+With a `-m` or `-M` option, will be renamed to .\n+If had a corresponding reflog, it is renamed to match\n+, and a reflog entry is created to remember the branch\n+renaming. If exists, -M must be used to force the rename\n to happen.\n \n The `-c` and `-C` options have the exact same semantics as `-m` and\n `-M`, except instead of the branch being renamed, it will be copied to a\n new name, along with its config and reflog.\n \n-With a `-d` or `-D` option, `` will be deleted. You may\n+With a `-d` or `-D` option, `` will be deleted. You may\n specify more than one branch for deletion. If the branch currently\n has a reflog then the reflog will also be deleted.\n \n@@ -107,7 +107,7 @@ OPTIONS\n --create-reflog::\n \tCreate the branch's reflog. This activates recording of\n \tall changes made to the branch ref, enabling use of date\n-\tbased sha1 expressions such as \"@\\{yesterday}\".\n+\tbased sha1 expressions such as \"@\\{yesterday}\".\n \tNote that in non-bare repositories, reflogs are usually\n \tenabled by default by the `core.logAllRefUpdates` config option.\n \tThe negated form `--no-create-reflog` only overrides an earlier\n@@ -116,7 +116,7 @@ OPTIONS\n \n -f::\n --force::\n-\tReset to , even if exists\n+\tReset to , even if exists\n \talready. Without `-f`, 'git branch' refuses to change an existing branch.\n \tIn combination with `-d` (or `--delete`), allow deleting the\n \tbranch irrespective of its merged status, or whether it even\n@@ -124,8 +124,8 @@ OPTIONS\n \t`-m` (or `--move`), allow renaming the branch even if the new\n \tbranch name already exists, the same applies for `-c` (or `--copy`).\n +\n-Note that 'git branch -f []', even with '-f',\n-refuses to change an existing branch `` that is checked out\n+Note that 'git branch -f []', even with '-f',\n+refuses to change an existing branch `` that is checked out\n in another worktree linked to the same repository.\n \n -m::\n@@ -255,7 +255,7 @@ how the `branch..remote` and `branch..merge` options are used.\n \tlinkgit:git-config[1]. Currently, only branch creation is\n \tsupported.\n +\n-When used in branch creation, a new branch will be created\n+When used in branch creation, a new branch will be created\n in the superproject and all of the submodules in the superproject's\n . In submodules, the branch will point to the submodule\n commit in the superproject's but the branch's tracking\n@@ -270,12 +270,12 @@ superproject's \"origin/main\", but tracks the submodule's \"origin/main\".\n \n -u ::\n --set-upstream-to=::\n-\tSet up 's tracking information so is\n-\tconsidered 's upstream branch. If no \n+\tSet up 's tracking information so is\n+\tconsidered 's upstream branch. If no \n \tis specified, then it defaults to the current branch.\n \n --unset-upstream::\n-\tRemove the upstream information for . If no branch\n+\tRemove the upstream information for . If no branch\n \tis specified it defaults to the current branch.\n \n --edit-description::\n@@ -300,8 +300,8 @@ superproject's \"origin/main\", but tracks the submodule's \"origin/main\".\n \tOnly list branches whose tips are not reachable from the\n \tspecified commit (HEAD if not specified). Implies `--list`.\n \n-::\n-\tThe name of the branch to create or delete.\n+::\n+\tThe name of the branch to create.\n \tThe new branch name must pass all checks defined by\n \tlinkgit:git-check-ref-format[1]. Some of these checks\n \tmay restrict the characters allowed in a branch name.\n@@ -311,14 +311,10 @@ superproject's \"origin/main\", but tracks the submodule's \"origin/main\".\n \tgiven as a branch name, a commit-id, or a tag. If this\n \toption is omitted, the current HEAD will be used instead.\n \n-::\n+::\n \tThe name of an existing branch. If this option is omitted,\n \tthe name of the current branch will be used instead.\n \n-::\n-\tThe new name for an existing branch. The same restrictions as for\n-\t apply.\n-\n --sort=::\n \tSort based on the key given. Prefix `-` to sort in descending\n \torder of the value. You may use the --sort= option\n-- \n2.44.0.rc2\n"},{"id":"489025","messageId":"b6d22f5a66de49efc623eceddbdc6faf@manjaro.org","threadId":"60928","inReplyTo":"96f1afa6-f4ac-4593-9bf4-72dafe3cab85@gmail.com","subject":"Re: [PATCH] branch: adjust documentation","fromName":"Dragan Simic","fromEmail":"dsimic@manjaro.org","sentAt":"2024-02-20T20:34:57Z","receivedAt":"2024-02-20T20:34:59Z","isPatch":true,"sender":{"key":"dsimic@manjaro.org","avatar":null},"body":"On 2024-02-20 21:25, Rubén Justo wrote:\n> Adjust the placeholders we use in Documentation/git-branch.txt to what\n> we say in CodingGuideLines:\n> \n> \tIf a placeholder has multiple words, they are separated by dashes:\n> \t \n> \t --template=\n> \n> Best viewed with --word-diff.\n> \n> Signed-off-by: Rubén Justo \n\nLooking good to me!\n\nReviewed-by: Dragan Simic \n\n> ---\n> \n> Documentation/git-branch.txt | 54 +++++++++++++++++-------------------\n> 1 file changed, 25 insertions(+), 29 deletions(-)\n> \n> diff --git a/Documentation/git-branch.txt \n> b/Documentation/git-branch.txt\n> index 0b08442932..489507e25f 100644\n> --- a/Documentation/git-branch.txt\n> +++ b/Documentation/git-branch.txt\n> @@ -17,13 +17,13 @@ SYNOPSIS\n> \t[(-r | --remotes) | (-a | --all)]\n> \t[--list] [...]\n> 'git branch' [--track[=(direct|inherit)] | --no-track] [-f]\n> -\t[--recurse-submodules] []\n> -'git branch' (--set-upstream-to= | -u ) \n> []\n> -'git branch' --unset-upstream []\n> -'git branch' (-m | -M) [] \n> -'git branch' (-c | -C) [] \n> -'git branch' (-d | -D) [-r] ...\n> -'git branch' --edit-description []\n> +\t[--recurse-submodules] []\n> +'git branch' (--set-upstream-to= | -u ) []\n> +'git branch' --unset-upstream []\n> +'git branch' (-m | -M) [] \n> +'git branch' (-c | -C) [] \n> +'git branch' (-d | -D) [-r] ...\n> +'git branch' --edit-description []\n> \n> DESCRIPTION\n> -----------\n> @@ -53,7 +53,7 @@ branches not merged into the named commit will be\n> listed. If the \n> argument is missing it defaults to `HEAD` (i.e. the tip of the current\n> branch).\n> \n> -The command's second form creates a new branch head named \n> +The command's second form creates a new branch head named \n> which points to the current `HEAD`, or if given. As a\n> special case, for , you may use `\"A...B\"` as a shortcut \n> for\n> the merge base of `A` and `B` if there is exactly one merge base. You\n> @@ -61,7 +61,7 @@ can leave out at most one of `A` and `B`, in which\n> case it defaults to\n> `HEAD`.\n> \n> Note that this will create the new branch, but it will not switch the\n> -working tree to it; use \"git switch \" to switch to the\n> +working tree to it; use \"git switch \" to switch to the\n> new branch.\n> \n> When a local branch is started off a remote-tracking branch, Git sets \n> up the\n> @@ -72,17 +72,17 @@ the remote-tracking branch. This behavior may be\n> changed via the global\n> overridden by using the `--track` and `--no-track` options, and\n> changed later using `git branch --set-upstream-to`.\n> \n> -With a `-m` or `-M` option, will be renamed to \n> .\n> -If had a corresponding reflog, it is renamed to match\n> -, and a reflog entry is created to remember the branch\n> -renaming. If exists, -M must be used to force the rename\n> +With a `-m` or `-M` option, will be renamed to .\n> +If had a corresponding reflog, it is renamed to match\n> +, and a reflog entry is created to remember the branch\n> +renaming. If exists, -M must be used to force the rename\n> to happen.\n> \n> The `-c` and `-C` options have the exact same semantics as `-m` and\n> `-M`, except instead of the branch being renamed, it will be copied to \n> a\n> new name, along with its config and reflog.\n> \n> -With a `-d` or `-D` option, `` will be deleted. You may\n> +With a `-d` or `-D` option, `` will be deleted. You may\n> specify more than one branch for deletion. If the branch currently\n> has a reflog then the reflog will also be deleted.\n> \n> @@ -107,7 +107,7 @@ OPTIONS\n> --create-reflog::\n> \tCreate the branch's reflog. This activates recording of\n> \tall changes made to the branch ref, enabling use of date\n> -\tbased sha1 expressions such as \"@\\{yesterday}\".\n> +\tbased sha1 expressions such as \"@\\{yesterday}\".\n> \tNote that in non-bare repositories, reflogs are usually\n> \tenabled by default by the `core.logAllRefUpdates` config option.\n> \tThe negated form `--no-create-reflog` only overrides an earlier\n> @@ -116,7 +116,7 @@ OPTIONS\n> \n> -f::\n> --force::\n> -\tReset to , even if exists\n> +\tReset to , even if exists\n> \talready. Without `-f`, 'git branch' refuses to change an existing \n> branch.\n> \tIn combination with `-d` (or `--delete`), allow deleting the\n> \tbranch irrespective of its merged status, or whether it even\n> @@ -124,8 +124,8 @@ OPTIONS\n> \t`-m` (or `--move`), allow renaming the branch even if the new\n> \tbranch name already exists, the same applies for `-c` (or `--copy`).\n> +\n> -Note that 'git branch -f []', even with \n> '-f',\n> -refuses to change an existing branch `` that is checked \n> out\n> +Note that 'git branch -f []', even with \n> '-f',\n> +refuses to change an existing branch `` that is checked \n> out\n> in another worktree linked to the same repository.\n> \n> -m::\n> @@ -255,7 +255,7 @@ how the `branch..remote` and\n> `branch..merge` options are used.\n> \tlinkgit:git-config[1]. Currently, only branch creation is\n> \tsupported.\n> +\n> -When used in branch creation, a new branch will be \n> created\n> +When used in branch creation, a new branch will be \n> created\n> in the superproject and all of the submodules in the superproject's\n> . In submodules, the branch will point to the submodule\n> commit in the superproject's but the branch's tracking\n> @@ -270,12 +270,12 @@ superproject's \"origin/main\", but tracks the\n> submodule's \"origin/main\".\n> \n> -u ::\n> --set-upstream-to=::\n> -\tSet up 's tracking information so is\n> -\tconsidered 's upstream branch. If no \n> +\tSet up 's tracking information so is\n> +\tconsidered 's upstream branch. If no \n> \tis specified, then it defaults to the current branch.\n> \n> --unset-upstream::\n> -\tRemove the upstream information for . If no branch\n> +\tRemove the upstream information for . If no branch\n> \tis specified it defaults to the current branch.\n> \n> --edit-description::\n> @@ -300,8 +300,8 @@ superproject's \"origin/main\", but tracks the\n> submodule's \"origin/main\".\n> \tOnly list branches whose tips are not reachable from the\n> \tspecified commit (HEAD if not specified). Implies `--list`.\n> \n> -::\n> -\tThe name of the branch to create or delete.\n> +::\n> +\tThe name of the branch to create.\n> \tThe new branch name must pass all checks defined by\n> \tlinkgit:git-check-ref-format[1]. Some of these checks\n> \tmay restrict the characters allowed in a branch name.\n> @@ -311,14 +311,10 @@ superproject's \"origin/main\", but tracks the\n> submodule's \"origin/main\".\n> \tgiven as a branch name, a commit-id, or a tag. If this\n> \toption is omitted, the current HEAD will be used instead.\n> \n> -::\n> +::\n> \tThe name of an existing branch. If this option is omitted,\n> \tthe name of the current branch will be used instead.\n> \n> -::\n> -\tThe new name for an existing branch. The same restrictions as for\n> -\t apply.\n> -\n> --sort=::\n> \tSort based on the key given. Prefix `-` to sort in descending\n> \torder of the value. You may use the --sort= option\n"},{"id":"489592","messageId":"d1f928b98238a60a96bee0d3f410deef@manjaro.org","threadId":"60928","inReplyTo":"b6d22f5a66de49efc623eceddbdc6faf@manjaro.org","subject":"Re: [PATCH] branch: adjust documentation","fromName":"Dragan Simic","fromEmail":"dsimic@manjaro.org","sentAt":"2024-02-28T02:19:29Z","receivedAt":"2024-02-28T02:19:33Z","isPatch":true,"sender":{"key":"dsimic@manjaro.org","avatar":null},"body":"Hello Junio,\n\nOn 2024-02-20 21:34, Dragan Simic wrote:\n> On 2024-02-20 21:25, Rubén Justo wrote:\n>> Adjust the placeholders we use in Documentation/git-branch.txt to what\n>> we say in CodingGuideLines:\n>> \n>> \tIf a placeholder has multiple words, they are separated by dashes:\n>> \t \n>> \t --template=\n>> \n>> Best viewed with --word-diff.\n>> \n>> Signed-off-by: Rubén Justo \n> \n> Looking good to me!\n\nJust checking, do you see the changes that Ruben proposed in this patch\nfit for our starting point in the git-branch documentation rewrite?\n\n> Reviewed-by: Dragan Simic \n> \n>> ---\n>> \n>> Documentation/git-branch.txt | 54 \n>> +++++++++++++++++-------------------\n>> 1 file changed, 25 insertions(+), 29 deletions(-)\n>> \n>> diff --git a/Documentation/git-branch.txt \n>> b/Documentation/git-branch.txt\n>> index 0b08442932..489507e25f 100644\n>> --- a/Documentation/git-branch.txt\n>> +++ b/Documentation/git-branch.txt\n>> @@ -17,13 +17,13 @@ SYNOPSIS\n>> \t[(-r | --remotes) | (-a | --all)]\n>> \t[--list] [...]\n>> 'git branch' [--track[=(direct|inherit)] | --no-track] [-f]\n>> -\t[--recurse-submodules] []\n>> -'git branch' (--set-upstream-to= | -u ) \n>> []\n>> -'git branch' --unset-upstream []\n>> -'git branch' (-m | -M) [] \n>> -'git branch' (-c | -C) [] \n>> -'git branch' (-d | -D) [-r] ...\n>> -'git branch' --edit-description []\n>> +\t[--recurse-submodules] []\n>> +'git branch' (--set-upstream-to= | -u ) \n>> []\n>> +'git branch' --unset-upstream []\n>> +'git branch' (-m | -M) [] \n>> +'git branch' (-c | -C) [] \n>> +'git branch' (-d | -D) [-r] ...\n>> +'git branch' --edit-description []\n>> \n>> DESCRIPTION\n>> -----------\n>> @@ -53,7 +53,7 @@ branches not merged into the named commit will be\n>> listed. If the \n>> argument is missing it defaults to `HEAD` (i.e. the tip of the \n>> current\n>> branch).\n>> \n>> -The command's second form creates a new branch head named \n>> \n>> +The command's second form creates a new branch head named \n>> \n>> which points to the current `HEAD`, or if given. As a\n>> special case, for , you may use `\"A...B\"` as a shortcut \n>> for\n>> the merge base of `A` and `B` if there is exactly one merge base. You\n>> @@ -61,7 +61,7 @@ can leave out at most one of `A` and `B`, in which\n>> case it defaults to\n>> `HEAD`.\n>> \n>> Note that this will create the new branch, but it will not switch the\n>> -working tree to it; use \"git switch \" to switch to the\n>> +working tree to it; use \"git switch \" to switch to the\n>> new branch.\n>> \n>> When a local branch is started off a remote-tracking branch, Git sets \n>> up the\n>> @@ -72,17 +72,17 @@ the remote-tracking branch. This behavior may be\n>> changed via the global\n>> overridden by using the `--track` and `--no-track` options, and\n>> changed later using `git branch --set-upstream-to`.\n>> \n>> -With a `-m` or `-M` option, will be renamed to \n>> .\n>> -If had a corresponding reflog, it is renamed to match\n>> -, and a reflog entry is created to remember the branch\n>> -renaming. If exists, -M must be used to force the rename\n>> +With a `-m` or `-M` option, will be renamed to .\n>> +If had a corresponding reflog, it is renamed to match\n>> +, and a reflog entry is created to remember the branch\n>> +renaming. If exists, -M must be used to force the rename\n>> to happen.\n>> \n>> The `-c` and `-C` options have the exact same semantics as `-m` and\n>> `-M`, except instead of the branch being renamed, it will be copied \n>> to a\n>> new name, along with its config and reflog.\n>> \n>> -With a `-d` or `-D` option, `` will be deleted. You may\n>> +With a `-d` or `-D` option, `` will be deleted. You may\n>> specify more than one branch for deletion. If the branch currently\n>> has a reflog then the reflog will also be deleted.\n>> \n>> @@ -107,7 +107,7 @@ OPTIONS\n>> --create-reflog::\n>> \tCreate the branch's reflog. This activates recording of\n>> \tall changes made to the branch ref, enabling use of date\n>> -\tbased sha1 expressions such as \"@\\{yesterday}\".\n>> +\tbased sha1 expressions such as \"@\\{yesterday}\".\n>> \tNote that in non-bare repositories, reflogs are usually\n>> \tenabled by default by the `core.logAllRefUpdates` config option.\n>> \tThe negated form `--no-create-reflog` only overrides an earlier\n>> @@ -116,7 +116,7 @@ OPTIONS\n>> \n>> -f::\n>> --force::\n>> -\tReset to , even if exists\n>> +\tReset to , even if exists\n>> \talready. Without `-f`, 'git branch' refuses to change an existing \n>> branch.\n>> \tIn combination with `-d` (or `--delete`), allow deleting the\n>> \tbranch irrespective of its merged status, or whether it even\n>> @@ -124,8 +124,8 @@ OPTIONS\n>> \t`-m` (or `--move`), allow renaming the branch even if the new\n>> \tbranch name already exists, the same applies for `-c` (or `--copy`).\n>> +\n>> -Note that 'git branch -f []', even with \n>> '-f',\n>> -refuses to change an existing branch `` that is checked \n>> out\n>> +Note that 'git branch -f []', even with \n>> '-f',\n>> +refuses to change an existing branch `` that is checked \n>> out\n>> in another worktree linked to the same repository.\n>> \n>> -m::\n>> @@ -255,7 +255,7 @@ how the `branch..remote` and\n>> `branch..merge` options are used.\n>> \tlinkgit:git-config[1]. Currently, only branch creation is\n>> \tsupported.\n>> +\n>> -When used in branch creation, a new branch will be \n>> created\n>> +When used in branch creation, a new branch will be \n>> created\n>> in the superproject and all of the submodules in the superproject's\n>> . In submodules, the branch will point to the submodule\n>> commit in the superproject's but the branch's tracking\n>> @@ -270,12 +270,12 @@ superproject's \"origin/main\", but tracks the\n>> submodule's \"origin/main\".\n>> \n>> -u ::\n>> --set-upstream-to=::\n>> -\tSet up 's tracking information so is\n>> -\tconsidered 's upstream branch. If no \n>> +\tSet up 's tracking information so is\n>> +\tconsidered 's upstream branch. If no \n>> \tis specified, then it defaults to the current branch.\n>> \n>> --unset-upstream::\n>> -\tRemove the upstream information for . If no branch\n>> +\tRemove the upstream information for . If no branch\n>> \tis specified it defaults to the current branch.\n>> \n>> --edit-description::\n>> @@ -300,8 +300,8 @@ superproject's \"origin/main\", but tracks the\n>> submodule's \"origin/main\".\n>> \tOnly list branches whose tips are not reachable from the\n>> \tspecified commit (HEAD if not specified). Implies `--list`.\n>> \n>> -::\n>> -\tThe name of the branch to create or delete.\n>> +::\n>> +\tThe name of the branch to create.\n>> \tThe new branch name must pass all checks defined by\n>> \tlinkgit:git-check-ref-format[1]. Some of these checks\n>> \tmay restrict the characters allowed in a branch name.\n>> @@ -311,14 +311,10 @@ superproject's \"origin/main\", but tracks the\n>> submodule's \"origin/main\".\n>> \tgiven as a branch name, a commit-id, or a tag. If this\n>> \toption is omitted, the current HEAD will be used instead.\n>> \n>> -::\n>> +::\n>> \tThe name of an existing branch. If this option is omitted,\n>> \tthe name of the current branch will be used instead.\n>> \n>> -::\n>> -\tThe new name for an existing branch. The same restrictions as for\n>> -\t apply.\n>> -\n>> --sort=::\n>> \tSort based on the key given. Prefix `-` to sort in descending\n>> \torder of the value. You may use the --sort= option\n"},{"id":"489617","messageId":"xmqqttlsld4t.fsf@gitster.g","threadId":"60928","inReplyTo":"d1f928b98238a60a96bee0d3f410deef@manjaro.org","subject":"Re: [PATCH] branch: adjust documentation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-02-28T17:20:02Z","receivedAt":"2024-02-28T17:20:04Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Dragan Simic writes:\n\n> Hello Junio,\n>\n> Just checking, do you see the changes that Ruben proposed in this patch\n> fit for our starting point in the git-branch documentation rewrite?\n\nThe synopsis part may, but with reservations. I know you two are\naiming to make this in many small incremental steps, but even then\nI'd have to say the way these placeholder words will be used in the\ntext part (both DESCRIPTION and OPTIONS) will be so different from\nthe final shape envisioned [*1*], the wording that may fit well within\nthe current text might not be the best fit in the final text.\n\nThe current description section talks about option and its arguments\nwithout showing the syntax, making it unnecessary to be extra\nverbose. For example, we see something like this:\n\n With a `-m` or `-M` option, will be renamed to\n . If had a corresponding reflog, it is\n renamed to match ...\n\nBut in the final shape of the documentation, I would like to see the\ndescription section not talk about these arguments, and would read\nmore like\n\n When given `-m` or `-M` options, the command renames an existing\n branch to a different name.\n\namong short descriptions made at the conceptual level on other modes\nlike \"listing\" mode, \"delete\" mode, etc. [*3*] \n\nAnd the option description would become something like [*]:\n\n -m [] ::\n\tRenames the branch (the current branch is used when\n\tnot given) to a new name , together with its reflog and\n\tconfiguration settings for the branch. ...\n\n Side note: and are meta-placeholders for the purpose\n of this document; Ruben's patch proposes to call them \n and .\n\nNow in such a context, and placeholders having actually\nthe word \"branch\" in it would sound redundant and awkward to read,\nEven though the choice of words Ruben made in the patch under\ndiscussion may work well in the current document structure. I\nsuspect these words will have to be chosen again when we start\nmaking the real organizational changes to the description and\noptions sections.\n\nIn other words, I do not think that the patch makes an effective\n\"one good step in the right direction\". At least, I couldn't see\nhow the wording for placeholders the patch proposes to use would be\nhelpful in deciding the placeholders used in the final version.\n\nThanks for pinging.\n\n\n[Footnotes]\n\n *1* Do we share the vision on how the final version should look\n like? Here I am assuming \"the final shape envisioned\" is along\n the lines of [*2*], i.e.\n\n (1) trim descriptions to just enumerate different modes of\n operations with explanation on what they do at the\n conceptual level;\n\n (2) make each entry in the options section self contained, by\n showing the option with their s, referring to\n them in the explanation text;\n\n (3) remove non-option from the options list.\n\n *2* https://lore.kernel.org/git/xmqqttmmlahf.fsf@gitster.g/\n\n *3* Because \"git branch\" does so many things, the DESCRIPTION\n section should first say the purpose of the section is to serve\n as brief catalog of features to help readers to find the entry\n in the option section to jump to quickly. Something like:\n\n The \"git branch\" command works in many modes (see SYNOPSIS\n above). By default the command works in the \"list\" option (the\n `--list` option explicitly asks for this mode).\n\n will be at the beginning of the section. The first four\n paragraphs in the current DESCRIPTION section is about this\n list mode. The first three of them should probably be moved to\n the OPTIONS section under `--list`. The fourth paragraph\n should be split and described in the entries of individual\n options it talks about in the OPTIONS section.\n.\n"},{"id":"489618","messageId":"xmqqplwglcy6.fsf@gitster.g","threadId":"60928","inReplyTo":"xmqqttlsld4t.fsf@gitster.g","subject":"Re: [PATCH] branch: adjust documentation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-02-28T17:24:01Z","receivedAt":"2024-02-28T17:24:13Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> The current description section talks about option and its arguments\n> without showing the syntax, making it unnecessary to be extra\n> verbose. For example, we see something like this:\n\n\"unnecessarily extra verbose\" is what I meant to say.\n"},{"id":"489646","messageId":"2c4ade0e3403f9b346e088b894d722c4@manjaro.org","threadId":"60928","inReplyTo":"xmqqttlsld4t.fsf@gitster.g","subject":"Re: [PATCH] branch: adjust documentation","fromName":"Dragan Simic","fromEmail":"dsimic@manjaro.org","sentAt":"2024-02-29T01:56:13Z","receivedAt":"2024-02-29T01:56:15Z","isPatch":true,"sender":{"key":"dsimic@manjaro.org","avatar":null},"body":"On 2024-02-28 18:20, Junio C Hamano wrote:\n> Dragan Simic writes:\n>> Just checking, do you see the changes that Ruben proposed in this \n>> patch\n>> fit for our starting point in the git-branch documentation rewrite?\n\nFirst of all, I _really_ appreciate your highly detailed feedback.\nThank you very much for taking the time to write it all down!\n\n> The synopsis part may, but with reservations. I know you two are\n> aiming to make this in many small incremental steps, but even then\n> I'd have to say the way these placeholder words will be used in the\n> text part (both DESCRIPTION and OPTIONS) will be so different from\n> the final shape envisioned [*1*], the wording that may fit well within\n> the current text might not be the best fit in the final text.\n\nPlease, let me remind you that I've already agreed upon doing it all\nin one fell swoop, which may consist of multiple patches in a series,\nbut applied as a whole.\n\n> The current description section talks about option and its arguments\n> without showing the syntax, making it unnecessary to be extra\n> verbose. For example, we see something like this:\n> \n> With a `-m` or `-M` option, will be renamed to\n> . If had a corresponding reflog, it is\n> renamed to match ...\n> \n> But in the final shape of the documentation, I would like to see the\n> description section not talk about these arguments, and would read\n> more like\n> \n> When given `-m` or `-M` options, the command renames an existing\n> branch to a different name.\n> \n> among short descriptions made at the conceptual level on other modes\n> like \"listing\" mode, \"delete\" mode, etc. [*3*]\n\nI agree on that being the final outcome, because the descriptions\nof arguments actually belong to the envisioned \"OPTIONS\" section,\nas part of the command descriptions.\n\n> And the option description would become something like [*]:\n> \n> -m [] ::\n> \tRenames the branch (the current branch is used when\n> \tnot given) to a new name , together with its reflog and\n> \tconfiguration settings for the branch. ...\n> \n> Side note: and are meta-placeholders for the purpose\n> of this document; Ruben's patch proposes to call them \n> and .\n> \n> Now in such a context, and placeholders having actually\n> the word \"branch\" in it would sound redundant and awkward to read,\n> Even though the choice of words Ruben made in the patch under\n> discussion may work well in the current document structure. I\n> suspect these words will have to be chosen again when we start\n> making the real organizational changes to the description and\n> options sections.\n\nWell, perhaps it's the best to revisit the argument naming later.\n\n> In other words, I do not think that the patch makes an effective\n> \"one good step in the right direction\". At least, I couldn't see\n> how the wording for placeholders the patch proposes to use would be\n> helpful in deciding the placeholders used in the final version.\n\nI see, thanks for the clarification.\n\n> [Footnotes]\n> \n> *1* Do we share the vision on how the final version should look\n> like? Here I am assuming \"the final shape envisioned\" is along\n> the lines of [*2*], i.e.\n> \n> (1) trim descriptions to just enumerate different modes of\n> operations with explanation on what they do at the\n> conceptual level;\n\nYes, that's also how I see it. The \"DESCRIPTION\" sections should\nend up describing only the available different modes.\n\n> (2) make each entry in the options section self contained, by\n> showing the option with their s, referring to\n> them in the explanation text;\n\nAgreed once again. The \"OPTIONS\" section should end up describing\nthe available options, together with their respective arguments, in\na way that doesn't require the reader to jump to other places in the\ndocument to fully understand each of the options.\n\n> (3) remove non-option from the options list.\n\nYes, that goes along with the descriptions being self-contained.\n\n> *2* https://lore.kernel.org/git/xmqqttmmlahf.fsf@gitster.g/\n\nSure, I already went through your message linked above, which already\ndescribed it quite well.\n\n> *3* Because \"git branch\" does so many things, the DESCRIPTION\n> section should first say the purpose of the section is to serve\n> as brief catalog of features to help readers to find the entry\n> in the option section to jump to quickly. Something like:\n\nYup, as I already explained it above. To reiterate, the purpose of\nthe \"DESCRIPTION\" section is to let the reader know what git-branch\ncan do, in form of easily readable prose.\n\n> The \"git branch\" command works in many modes (see SYNOPSIS\n> above). By default the command works in the \"list\" option (the\n> `--list` option explicitly asks for this mode).\n> \n> will be at the beginning of the section. The first four\n> paragraphs in the current DESCRIPTION section is about this\n> list mode. The first three of them should probably be moved to\n> the OPTIONS section under `--list`. The fourth paragraph\n> should be split and described in the entries of individual\n> options it talks about in the OPTIONS section.\n\nAgreed, once again. :) Most of the prose currently found in the\n\"DESCRIPTION\" section should actually be moved to the various command\ndescriptions in the envisioned future \"OPTIONS\" section.\n"},{"id":"489674","messageId":"cbaf17e7-37a6-4c2e-82ba-65fe41dd86b1@gmail.com","threadId":"60928","inReplyTo":"xmqqttlsld4t.fsf@gitster.g","subject":"Re: [PATCH] branch: adjust documentation","fromName":"Rubén Justo","fromEmail":"rjusto@gmail.com","sentAt":"2024-02-29T18:56:05Z","receivedAt":"2024-02-29T18:56:09Z","isPatch":true,"sender":{"key":"rjusto@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5685487?v=4"},"body":"On Wed, Feb 28, 2024 at 09:20:02 -0800, Junio C Hamano wrote:\n\n> The current description section talks about option and its arguments\n> without showing the syntax, making it unnecessarily extra verbose.\n> For example, we see something like this:\n> \n> With a `-m` or `-M` option, will be renamed to\n> . If had a corresponding reflog, it is\n> renamed to match ...\n> \n> But in the final shape of the documentation, I would like to see the\n> description section not talk about these arguments, and would read\n> more like\n> \n> When given `-m` or `-M` options, the command renames an existing\n> branch to a different name.\n> \n\nGood.\n\n> among short descriptions made at the conceptual level on other modes\n> like \"listing\" mode, \"delete\" mode, etc. [*3*] \n> \n> And the option description would become something like [*]:\n> \n> -m [] ::\n> \tRenames the branch (the current branch is used when\n> \tnot given) to a new name , together with its reflog and\n> \tconfiguration settings for the branch. ...\n\n> Now in such a context, and placeholders having actually\n> the word \"branch\" in it would sound redundant and awkward to read,\n\nIndeed.\n\nBut I'm on the fence. Do we have to use \"Renames the branch \"?\n\nIf we wisely choose the placeholder, perhaps we can write:\n\n -m [] ::\n\tRenames (the current branch is used when not given) to\n\ta new name , together with its reflog and configuration\n\tsettings ...\n\nAnd if is _good enough_ then \"current branch is used when ...\"\nshould seem somewhat redundant. So it could be possible to end up\nhaving something like:\n\n -m [] ::\n\tRenames to a new name , together with its reflog\n\tand configuration settings ...\n\nAre we going to say \"the current branch is used when ...\" in the\ndescription for the other options too? The description for \"-c|-C\",\n\"--edit-description\", \"--unset-upstream\", ... Perhaps we are, and it\nwill sound repetitive. However, even if we do, with the _good enough_\nplaceholder the user will be able to fill the gaps we might leave in\nthe documentation, like the one that presumably has bring us here:\npull.1613.git.git.1701303891791.gitgitgadget@gmail.com.\n\nAnd finally; Can't and be consistent with other bits we\nhave in the documentation like the descriptions of \"git switch \",\n\"git checkout -b \" or \"git init -b \"?\n\nAfter the revamp, I'll be less happy (but happy :-) nonetheless) if we\nend up having a SYNOPSIS similar to the one we have today:\n\n - Documentation/git-branch.txt:\n 'git branch' (-c | -C) [] \n 'git branch' (-d | -D) [-r] ...\n 'git branch' --edit-description []\n\nIt seems to me to be made up of disconnected pieces.\n\nAnd for reference:\n\n - Documentation/git-switch.txt:\n 'git switch' [] [--no-guess] \n 'git switch' [] --orphan \n\n - Documentation/git-init.txt:\n 'git init' [--initial-branch=]\n\nMy apologies if I'm pushing too hard on this and being reiterative in\nmy messages in this series. My intention has been to explore the use\nwe want of the placeholders. Of course, this is not at odds with my\nsympathy for the vision proposed. I agree on the direction.\n\n> Even though the choice of words Rubén made in the patch under\n> discussion may work well in the current document structure.\n\nMy patch is mainly about CodingGuideLines:\n\n\tIf a placeholder has multiple words, they are separated by dashes:\n\t \n\t --template=\n"},{"id":"489682","messageId":"xmqqcysff4l7.fsf@gitster.g","threadId":"60928","inReplyTo":"cbaf17e7-37a6-4c2e-82ba-65fe41dd86b1@gmail.com","subject":"Re: [PATCH] branch: adjust documentation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-02-29T19:33:24Z","receivedAt":"2024-02-29T19:33:35Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Rubén Justo writes:\n\n> If we wisely choose the placeholder, perhaps we can write:\n>\n> -m [] ::\n> \tRenames (the current branch is used when not given) to\n> \ta new name , together with its reflog and configuration\n> \tsettings ...\n>\n> And if is _good enough_ then \"current branch is used when ...\"\n> should seem somewhat redundant. So it could be possible to end up\n> having something like:\n>\n> -m [] ::\n> \tRenames to a new name , together with its reflog\n> \tand configuration settings ...\n\nIf you use or something\nawkward like that as , surely you can. But I do not think we\nwant to go there. And neither or would\nremove the need for \"if omitted then the current branch is used\", I\nam afraid, even though there may be a way to rephrase it more\nconcisely, e.g. \"Rename the current branch (or when given)...\"\n\n> Are we going to say \"the current branch is used when ...\" in the\n> description for the other options too? The description for \"-c|-C\",\n> \"--edit-description\", \"--unset-upstream\", ... Perhaps we are, and it\n> will sound repetitive.\n\nDo not forget that the objective of the larger-picture-revamping of\nthis page is to make the description of each option self-contained.\nSimilarity between -m's description and -c's description does not\ncount as being uselessly repetitive.\n\n>> Even though the choice of words Rubén made in the patch under\n>> discussion may work well in the current document structure.\n>\n> My patch is mainly about CodingGuideLines:\n>\n> \tIf a placeholder has multiple words, they are separated by dashes:\n> \t \n> \t --template=\n\nYes, and that will be something we want to address _after_ we pick\nwhat word or phrase would replace or in the above at the\nconceptual level. If we picked a single word, say \"branch\", we do\nnot even need to worry about dashes, and spell it just . If\nwe did not pick \"old branch\", then we'd use \"\", but doing\nsuch a conversion based on the current text is a wasted work, if we\nend up using say \"original branch\" as the phrase, for example.\n\nSo if your patch is mainly about that part of the guideline, it is\naddressing the documentation update in a wrong order, creating\npossibly a wasted work.\n"},{"id":"489687","messageId":"d456a80d-5c2b-421b-a849-3c7cce288c6c@gmail.com","threadId":"60928","inReplyTo":"xmqqcysff4l7.fsf@gitster.g","subject":"Re: [PATCH] branch: adjust documentation","fromName":"Rubén Justo","fromEmail":"rjusto@gmail.com","sentAt":"2024-02-29T20:02:17Z","receivedAt":"2024-02-29T20:02:20Z","isPatch":true,"sender":{"key":"rjusto@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5685487?v=4"},"body":"On Thu, Feb 29, 2024 at 11:33:24AM -0800, Junio C Hamano wrote:\n\n> Do not forget that the objective of the larger-picture-revamping of\n> this page is to make the description of each option self-contained.\n> Similarity between -m's description and -c's description does not\n> count as being uselessly repetitive.\n\nOK. I was not considering this.\n\nThanks.\n"},{"id":"489689","messageId":"253d3c827f6e389d533c60113b08f94f@manjaro.org","threadId":"60928","inReplyTo":"d456a80d-5c2b-421b-a849-3c7cce288c6c@gmail.com","subject":"Re: [PATCH] branch: adjust documentation","fromName":"Dragan Simic","fromEmail":"dsimic@manjaro.org","sentAt":"2024-02-29T20:09:25Z","receivedAt":"2024-02-29T20:09:32Z","isPatch":true,"sender":{"key":"dsimic@manjaro.org","avatar":null},"body":"On 2024-02-29 21:02, Rubén Justo wrote:\n> On Thu, Feb 29, 2024 at 11:33:24AM -0800, Junio C Hamano wrote:\n> \n>> Do not forget that the objective of the larger-picture-revamping of\n>> this page is to make the description of each option self-contained.\n>> Similarity between -m's description and -c's description does not\n>> count as being uselessly repetitive.\n> \n> OK. I was not considering this.\n\nI'd also like to avoid repetition, but if we want to have self-contained\ncommand descriptions (which is good), some repetition is unavoidable.\nIn fact, we can see what avoiding the repetition has lead us to in the\ncurrent state of the git-branch(1) man page.\n"},{"id":"489777","messageId":"a434de37-7485-4d51-86c4-14b0f477db0c@gmail.com","threadId":"60928","inReplyTo":"253d3c827f6e389d533c60113b08f94f@manjaro.org","subject":"Re: [PATCH] branch: adjust documentation","fromName":"Rubén Justo","fromEmail":"rjusto@gmail.com","sentAt":"2024-03-02T16:18:16Z","receivedAt":"2024-03-02T16:18:23Z","isPatch":true,"sender":{"key":"rjusto@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5685487?v=4"},"body":"On Thu, Feb 29, 2024 at 09:09:25PM +0100, Dragan Simic wrote:\n> On 2024-02-29 21:02, Rubén Justo wrote:\n> > On Thu, Feb 29, 2024 at 11:33:24AM -0800, Junio C Hamano wrote:\n> > \n> > > Do not forget that the objective of the larger-picture-revamping of\n> > > this page is to make the description of each option self-contained.\n> > > Similarity between -m's description and -c's description does not\n> > > count as being uselessly repetitive.\n> > \n> > OK. I was not considering this.\n> \n> I'd also like to avoid repetition, but if we want to have self-contained\n> command descriptions (which is good), some repetition is unavoidable.\n\nI don't see much of a problem with repetitions. Within the\nself-containmnent aspect it makes a lot of sense. And, after all, my\nmessages have been mainly about repeating ... placeholders.\n\n> In fact, we can see what avoiding the repetition has lead us to in the\n> current state of the git-branch(1) man page.\n\nIndeed. I agree that the lack of repetition has brought us here. But I\nthink we're not 100% aligned in what repetition is :-), yet. We're\nworking on it!\n\nThanks.\n"}]}