{"thread":{"id":"60690","subject":"[PATCH] branch: clarify term","startedAt":"2024-01-06T14:38:46Z","lastAt":"2024-01-08T18:04:58Z","messageCount":2,"participants":["Rubén Justo","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"486363","messageId":"d38e5a18-4d85-48f3-bc8b-8ca02ea683a4@gmail.com","threadId":"60690","inReplyTo":null,"subject":"[PATCH] branch: clarify term","fromName":"Rubén Justo","fromEmail":"rjusto@gmail.com","sentAt":"2024-01-06T14:38:37Z","receivedAt":"2024-01-06T14:38:46Z","isPatch":true,"sender":{"key":"rjusto@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5685487?v=4"},"body":"Since 52d59cc645 (branch: add a --copy (-c) option to go with --move\n(-m), 2017-06-18) is used in more operations than just -m.\n\nLet's also clarify what we do if is omitted.\n\nSigned-off-by: Rubén Justo \n---\n Documentation/git-branch.txt | 3 ++-\n 1 file changed, 2 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt\nindex 4395aa9354..233264549c 100644\n--- a/Documentation/git-branch.txt\n+++ b/Documentation/git-branch.txt\n@@ -312,7 +312,8 @@ superproject's \"origin/main\", but tracks the submodule's \"origin/main\".\n \toption is omitted, the current HEAD will be used instead.\n \n ::\n-\tThe name of an existing branch to rename.\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-- \n2.42.0\n"},{"id":"486403","messageId":"xmqq8r4zln08.fsf@gitster.g","threadId":"60690","inReplyTo":"d38e5a18-4d85-48f3-bc8b-8ca02ea683a4@gmail.com","subject":"Re: [PATCH] branch: clarify term","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-01-08T18:04:55Z","receivedAt":"2024-01-08T18:04:58Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Rubén Justo writes:\n\n> Since 52d59cc645 (branch: add a --copy (-c) option to go with --move\n> (-m), 2017-06-18) is used in more operations than just -m.\n>\n> Let's also clarify what we do if is omitted.\n>\n> Signed-off-by: Rubén Justo \n> ---\n> Documentation/git-branch.txt | 3 ++-\n> 1 file changed, 2 insertions(+), 1 deletion(-)\n>\n> diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt\n> index 4395aa9354..233264549c 100644\n> --- a/Documentation/git-branch.txt\n> +++ b/Documentation/git-branch.txt\n> @@ -312,7 +312,8 @@ superproject's \"origin/main\", but tracks the submodule's \"origin/main\".\n> \toption is omitted, the current HEAD will be used instead.\n> \n> ::\n> -\tThe name of an existing branch to rename.\n> +\tThe name of an existing branch. If this option is omitted,\n> +\tthe name of the current branch will be used instead.\n\nThanks.\n\nWill queue this patch as is for now, but I suspect that in the\nlonger term it will help readers a lot to revamp the whole page.\nThe description for the \"branch rename\" operation, for example, is\nsplit and partly repreated in three places, i.e. \n\n * a paragraph in the DESCRIPTION that talks about ,\n where readers will be helped by the same clarification as this\n patch gives;\n\n * -m/-M option description which is very sketchy and does not even\n hint that they take and ; and\n\n * description as a separate bullet item in the same\n list, which does not even hint that this is used by -m/-M.\n\nwhich is unmanageable from writers' point of view, and hard to\nfollow from readers' point of view.\n\nSuch a rewrite may look like this:\n\n * Trim down the DESCRIPTION explanation to enumerate \"features\"\n offered, with pointers into the OPTIONS section using the option\n names as hints, e.g.,\n\n The command offers many features that work on branches,\n depending on the options.\n\n - The default mode of operation is to list (the --list option\n explicitly calls for it, or the lack of other options to\n trigger different mode).\n\n - ...\n\n - An existing branch can be renamed to a different name with\n \"-m/-M\" options.\n\n - ...\n\n * Enhance the description in the OPTIONS section so that each\n bullet item (e.g., \"-m\") gives everything the user wants to know\n about that option, e.g.,\n\n -m [] ::\n -M [] ::\n Rename (defaults to the current branch) to\n . If already exists, `-m` will error\n out and renaming must be forced by using `-M` (in other\n words, `-M` works as a short-hand for `-m --force`).\n +\n The contents reflog of the will also be renamed to become\n the reflog of the , and a reflog entry is added for\n the renaming of the branch.\n\n * Remove the non-option entries from the OPTIONS bullet list.\n\n"}]}