{"thread":{"id":"60936","subject":"[PATCH v2] branch: rework the descriptions of rename and copy operations","startedAt":"2024-02-16T12:44:32Z","lastAt":"2024-02-16T21:58:41Z","messageCount":5,"participants":["Dragan Simic","Junio C Hamano"],"isPatch":true,"patchVersion":2,"patchTotal":null},"messages":[{"id":"488796","messageId":"6e1c3f2c5816f09aab561bc7dec2b7455d70aaec.1708087213.git.dsimic@manjaro.org","threadId":"60936","inReplyTo":null,"subject":"[PATCH v2] branch: rework the descriptions of rename and copy operations","fromName":"Dragan Simic","fromEmail":"dsimic@manjaro.org","sentAt":"2024-02-16T12:44:19Z","receivedAt":"2024-02-16T12:44:32Z","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, the version 1 is effectively version 2 of the original patch.\n The version 1 of the patch includes detailed feedback from Kyle and Junio,\n who suggested moving/adding the argument descriptions to their respective\n commands. This resulted in more significant changes to the contents of the\n git-branch(1) man page, in an attempt to make it more readable.\n \n The version 2 includes feedback from Kristoffer and Junio, by improving the\n wording of the opening sentences in the descriptions of branch rename and\n copy operations, and by mentioning the additional reflog entry created while\n renaming a branch, which was omitted in the v1 by mistake.\n \n [3] https://lore.kernel.org/git/e2eb777bca8ffeec42bdd684837d28dd52cfc9c3.1707136999.git.dsimic@manjaro.org/T/#u\n\n Documentation/git-branch.txt | 51 ++++++++++++++++--------------------\n 1 file changed, 23 insertions(+), 28 deletions(-)\n\ndiff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt\nindex 0b0844293235..d52b5e8dbacd 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,31 @@ 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-\n--M::\n+-m [] ::\n+--move [] ::\n+\tRename an existing branch `` to ``; if left\n+\tunspecified, `` defaults to the current branch. The\n+\tconfiguration variables for the `` branch and its reflog\n+\tare also renamed appropriately to be used with ``. In\n+\taddition, a reflog entry is created to remember the branch renaming.\n+\tRenaming fails if branch `` already exists, but `-M`\n+\tor `--move --force` can be used to overwrite the contents of the\n+\texisting branch `` while renaming.\n+\n+-M [] ::\n \tShortcut for `--move --force`.\n \n--c::\n---copy::\n-\tCopy a branch, together with its config and reflog.\n-\n--C::\n+-c [] ::\n+--copy [] ::\n+\tCopy an existing branch `` to ``; if left\n+\tunspecified, `` defaults to the current branch. The\n+\tconfiguration variables for the `` branch and its reflog\n+\tare also copied appropriately to be used with ``.\n+\tCopying fails if branch `` already exists, but `-C`\n+\tor `--copy --force` can be used to overwrite the contents of the\n+\texisting branch `` while copying.\n+\n+-C [] ::\n \tShortcut for `--copy --force`.\n \n --color[=]::\n@@ -311,14 +314,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":"488808","messageId":"xmqq1q9ci3jt.fsf@gitster.g","threadId":"60936","inReplyTo":"6e1c3f2c5816f09aab561bc7dec2b7455d70aaec.1708087213.git.dsimic@manjaro.org","subject":"Re: [PATCH v2] branch: rework the descriptions of rename and copy operations","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-02-16T19:59:02Z","receivedAt":"2024-02-16T19:59:06Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Dragan Simic writes:\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\nThe intention to remove non-option from the OPTIONS enumeration,\nand to explain and used as arguments to -m and -c where\nthese options are described, are both very good (heh, after all,\nthey are parts of what I envisioned to be the way to go in the\nlonger term ;-).\n\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\nBut the halfway modification to the description section in this\npatch is not an improvement. It makes some options described there\nwhile -m and -c are completely missing now, making the section\nincomplete and coverage of the operating modes of the command\nuneven. \n\n> +-m [] ::\n> +--move [] ::\n> +\tRename an existing branch `` to ``; if left\n> +\tunspecified, `` defaults to the current branch. The\n> +\tconfiguration variables for the `` branch and its reflog\n> +\tare also renamed appropriately to be used with ``. In\n> +\taddition, a reflog entry is created to remember the branch renaming.\n> +\tRenaming fails if branch `` already exists, but `-M`\n> +\tor `--move --force` can be used to overwrite the contents of the\n> +\texisting branch `` while renaming.\n\nOK. This is way more readable than the previous attempts we made.\n\nThe description of the single failure mode still worries me (see my\nprevious message on this). Here is my attempt:\n\n\tWhen the command fails due to an existing '', you\n\tcan use `-M` (or `--move --force`) to force overwriting it.\n\nto hint that there may be other ways for the command to fail, and\nhint that `-M` may not always resolve issues, but I do not know how\nsuccessful it is. I could add\n\n\tNote that `-M ` will not resolve an error if the\n\treason why `-m` fails is to protect the other worktree that\n\tchecks out (or otherwise uses) and points at a\n\tdifferent commit.\n\nbut we do not necessarily want to appear to be exhaustive here, so,\nI dunno.\n\n> +-M [] ::\n> \tShortcut for `--move --force`.\n\nOK.\n\n> +--copy [] ::\n> +\tCopy an existing branch `` to ``; if left\n> +\tunspecified, `` defaults to the current branch. The\n> +\tconfiguration variables for the `` branch and its reflog\n> +\tare also copied appropriately to be used with ``.\n> +\tCopying fails if branch `` already exists, but `-C`\n> +\tor `--copy --force` can be used to overwrite the contents of the\n> +\texisting branch `` while copying.\n\nExactly the same comment on \"other failure modes\" applies here.\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\nRemovals of these lines are very pleasing ;-).\n"},{"id":"488814","messageId":"608b4e81d71a95c820f1e4068382d391@manjaro.org","threadId":"60936","inReplyTo":"xmqq1q9ci3jt.fsf@gitster.g","subject":"Re: [PATCH v2] branch: rework the descriptions of rename and copy operations","fromName":"Dragan Simic","fromEmail":"dsimic@manjaro.org","sentAt":"2024-02-16T21:20:02Z","receivedAt":"2024-02-16T21:20:11Z","isPatch":true,"sender":{"key":"dsimic@manjaro.org","avatar":null},"body":"Hello Junio,\n\nOn 2024-02-16 20:59, Junio C Hamano wrote:\n> Dragan Simic writes:\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 intention to remove non-option from the OPTIONS enumeration,\n> and to explain and used as arguments to -m and -c where\n> these options are described, are both very good (heh, after all,\n> they are parts of what I envisioned to be the way to go in the\n> longer term ;-).\n\nYes, that's what I plan to work on after this patch is, hopefully,\naccepted (see also below). My initial hope was that we'd define\nthe general outline for the completely reworked git-branch(1) even\nfurther with this patch, which should in turn make the future work\nmore efficient. I think we're on a good way. :)\n\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> \n> But the halfway modification to the description section in this\n> patch is not an improvement. It makes some options described there\n> while -m and -c are completely missing now, making the section\n> incomplete and coverage of the operating modes of the command\n> uneven.\n\nIf I got it right, you'd prefer this patch not to be accepted\nseparately, but as part of the future series that would rework the\nentire git-branch(1) man page? I'm fine with that as well.\n\n>> +-m [] ::\n>> +--move [] ::\n>> +\tRename an existing branch `` to ``; if left\n>> +\tunspecified, `` defaults to the current branch. The\n>> +\tconfiguration variables for the `` branch and its reflog\n>> +\tare also renamed appropriately to be used with ``. In\n>> +\taddition, a reflog entry is created to remember the branch renaming.\n>> +\tRenaming fails if branch `` already exists, but `-M`\n>> +\tor `--move --force` can be used to overwrite the contents of the\n>> +\texisting branch `` while renaming.\n> \n> OK. This is way more readable than the previous attempts we made.\n> \n> The description of the single failure mode still worries me (see my\n> previous message on this). Here is my attempt:\n> \n> \tWhen the command fails due to an existing '', you\n> \tcan use `-M` (or `--move --force`) to force overwriting it.\n> \n> to hint that there may be other ways for the command to fail, and\n> hint that `-M` may not always resolve issues, but I do not know how\n> successful it is. I could add\n\nMakes sense. It's intentionally a bit vague, but should work fine.\nI'd just replace \"the command\" with \"renaming\", and avoid addressing\nthe reader directly.\n\n> \tNote that `-M ` will not resolve an error if the\n> \treason why `-m` fails is to protect the other worktree that\n> \tchecks out (or otherwise uses) and points at a\n> \tdifferent commit.\n> \n> but we do not necessarily want to appear to be exhaustive here, so,\n> I dunno.\n\nHuh-uh... I'm not sure that such an exhaustive explanation would\nmake it more clear to the majority of users. Perhaps it's better\nto remain a bit vague, at least for now, and omit such details.\n\n>> +-M [] ::\n>> \tShortcut for `--move --force`.\n> \n> OK.\n> \n>> +--copy [] ::\n>> +\tCopy an existing branch `` to ``; if left\n>> +\tunspecified, `` defaults to the current branch. The\n>> +\tconfiguration variables for the `` branch and its reflog\n>> +\tare also copied appropriately to be used with ``.\n>> +\tCopying fails if branch `` already exists, but `-C`\n>> +\tor `--copy --force` can be used to overwrite the contents of the\n>> +\texisting branch `` while copying.\n> \n> Exactly the same comment on \"other failure modes\" applies here.\n\nNoted.\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> \n> Removals of these lines are very pleasing ;-).\n\nOh yes, it's like a clear embodiment of making the current mess\na little bit smaller. :)\n"},{"id":"488815","messageId":"xmqqh6i8gk20.fsf@gitster.g","threadId":"60936","inReplyTo":"608b4e81d71a95c820f1e4068382d391@manjaro.org","subject":"Re: [PATCH v2] branch: rework the descriptions of rename and copy operations","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-02-16T21:45:27Z","receivedAt":"2024-02-16T21:45:32Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Dragan Simic writes:\n\n>> But the halfway modification to the description section in this\n>> patch is not an improvement. It makes some options described there\n>> while -m and -c are completely missing now, making the section\n>> incomplete and coverage of the operating modes of the command\n>> uneven.\n>\n> If I got it right, you'd prefer this patch not to be accepted\n> separately, but as part of the future series that would rework the\n> entire git-branch(1) man page? I'm fine with that as well.\n\nNot necessarily. If you wanted to this this in multiple steps, we\ncan first whip the OPTIONS part into a good shape, and then fix the\nDESCRIPTION part.\n\nWhat we want to avoid (not limited to this topic) is to say \"this\ntemporarily makes things worse here, but trust me it will eventually\nbecome perfect\". Removing only -m/-c from the description section\nmakes the description section worse than before the patch---we'd be\nbetter off leaving the original as-is if we are not revamping the\nentire section.\n\n\n"},{"id":"488817","messageId":"7fc9dddac54d09f706419c903911a73c@manjaro.org","threadId":"60936","inReplyTo":"xmqqh6i8gk20.fsf@gitster.g","subject":"Re: [PATCH v2] branch: rework the descriptions of rename and copy operations","fromName":"Dragan Simic","fromEmail":"dsimic@manjaro.org","sentAt":"2024-02-16T21:58:39Z","receivedAt":"2024-02-16T21:58:41Z","isPatch":true,"sender":{"key":"dsimic@manjaro.org","avatar":null},"body":"On 2024-02-16 22:45, Junio C Hamano wrote:\n> Dragan Simic writes:\n> \n>>> But the halfway modification to the description section in this\n>>> patch is not an improvement. It makes some options described there\n>>> while -m and -c are completely missing now, making the section\n>>> incomplete and coverage of the operating modes of the command\n>>> uneven.\n>> \n>> If I got it right, you'd prefer this patch not to be accepted\n>> separately, but as part of the future series that would rework the\n>> entire git-branch(1) man page? I'm fine with that as well.\n> \n> Not necessarily. If you wanted to this this in multiple steps, we\n> can first whip the OPTIONS part into a good shape, and then fix the\n> DESCRIPTION part.\n\nI'll think a bit more about it, to see what might be our best choice\nmoving forward.\n\n> What we want to avoid (not limited to this topic) is to say \"this\n> temporarily makes things worse here, but trust me it will eventually\n> become perfect\". Removing only -m/-c from the description section\n> makes the description section worse than before the patch---we'd be\n> better off leaving the original as-is if we are not revamping the\n> entire section.\n\nThe way you wrote this brought a smile to my face. :) I agree, making\nthings a bit worse while promising perfection later is rarely justified.\nPerhaps only when some nasty bug has to be fixed ASAP.\n"}]}