Re: [PATCH] branch: adjust documentation

[Dragan Simic <dsimic@manjaro.org>]

Hello Junio,

On 2024-02-20 21:34, Dragan Simic wrote:
> On 2024-02-20 21:25, Rubén Justo wrote:
>> Adjust the placeholders we use in Documentation/git-branch.txt to what
>> we say in CodingGuideLines:
>> 
>> 	If a placeholder has multiple words, they are separated by dashes:
>> 	  <new-branch-name>
>> 	  --template=<template-directory>
>> 
>> Best viewed with --word-diff.
>> 
>> Signed-off-by: Rubén Justo <rjusto@gmail.com>
> 
> Looking good to me!

Just checking, do you see the changes that Ruben proposed in this patch
fit for our starting point in the git-branch documentation rewrite?

> Reviewed-by: Dragan Simic <dsimic@manjaro.org>
> 
>> ---
>> 
>>  Documentation/git-branch.txt | 54 
>> +++++++++++++++++-------------------
>>  1 file changed, 25 insertions(+), 29 deletions(-)
>> 
>> diff --git a/Documentation/git-branch.txt 
>> b/Documentation/git-branch.txt
>> index 0b08442932..489507e25f 100644
>> --- a/Documentation/git-branch.txt
>> +++ b/Documentation/git-branch.txt
>> @@ -17,13 +17,13 @@ SYNOPSIS
>>  	[(-r | --remotes) | (-a | --all)]
>>  	[--list] [<pattern>...]
>>  'git branch' [--track[=(direct|inherit)] | --no-track] [-f]
>> -	[--recurse-submodules] <branchname> [<start-point>]
>> -'git branch' (--set-upstream-to=<upstream> | -u <upstream>) 
>> [<branchname>]
>> -'git branch' --unset-upstream [<branchname>]
>> -'git branch' (-m | -M) [<oldbranch>] <newbranch>
>> -'git branch' (-c | -C) [<oldbranch>] <newbranch>
>> -'git branch' (-d | -D) [-r] <branchname>...
>> -'git branch' --edit-description [<branchname>]
>> +	[--recurse-submodules] <new-branch> [<start-point>]
>> +'git branch' (--set-upstream-to=<upstream> | -u <upstream>) 
>> [<branch>]
>> +'git branch' --unset-upstream [<branch>]
>> +'git branch' (-m | -M) [<branch>] <new-branch>
>> +'git branch' (-c | -C) [<branch>] <new-branch>
>> +'git branch' (-d | -D) [-r] <branch>...
>> +'git branch' --edit-description [<branch>]
>> 
>>  DESCRIPTION
>>  -----------
>> @@ -53,7 +53,7 @@ branches not merged into the named commit will be
>> listed.  If the <commit>
>>  argument is missing it defaults to `HEAD` (i.e. the tip of the 
>> current
>>  branch).
>> 
>> -The command's second form creates a new branch head named 
>> <branchname>
>> +The command's second form creates a new branch head named 
>> <new-branch>
>>  which points to the current `HEAD`, or <start-point> if given. As a
>>  special case, for <start-point>, you may use `"A...B"` as a shortcut 
>> for
>>  the merge base of `A` and `B` if there is exactly one merge base. You
>> @@ -61,7 +61,7 @@ can leave out at most one of `A` and `B`, in which
>> case it defaults to
>>  `HEAD`.
>> 
>>  Note that this will create the new branch, but it will not switch the
>> -working tree to it; use "git switch <newbranch>" to switch to the
>> +working tree to it; use "git switch <new-branch>" to switch to the
>>  new branch.
>> 
>>  When a local branch is started off a remote-tracking branch, Git sets 
>> up the
>> @@ -72,17 +72,17 @@ the remote-tracking branch. This behavior may be
>> changed via the global
>>  overridden by using the `--track` and `--no-track` options, and
>>  changed later using `git branch --set-upstream-to`.
>> 
>> -With a `-m` or `-M` option, <oldbranch> will be renamed to 
>> <newbranch>.
>> -If <oldbranch> had a corresponding reflog, it is renamed to match
>> -<newbranch>, and a reflog entry is created to remember the branch
>> -renaming. If <newbranch> exists, -M must be used to force the rename
>> +With a `-m` or `-M` option, <branch> will be renamed to <new-branch>.
>> +If <branch> had a corresponding reflog, it is renamed to match
>> +<new-branch>, and a reflog entry is created to remember the branch
>> +renaming. If <new-branch> exists, -M must be used to force the rename
>>  to happen.
>> 
>>  The `-c` and `-C` options have the exact same semantics as `-m` and
>>  `-M`, except instead of the branch being renamed, it will be copied 
>> to a
>>  new name, along with its config and reflog.
>> 
>> -With a `-d` or `-D` option, `<branchname>` will be deleted.  You may
>> +With a `-d` or `-D` option, `<branch>` will be deleted.  You may
>>  specify more than one branch for deletion.  If the branch currently
>>  has a reflog then the reflog will also be deleted.
>> 
>> @@ -107,7 +107,7 @@ OPTIONS
>>  --create-reflog::
>>  	Create the branch's reflog.  This activates recording of
>>  	all changes made to the branch ref, enabling use of date
>> -	based sha1 expressions such as "<branchname>@\{yesterday}".
>> +	based sha1 expressions such as "<branch>@\{yesterday}".
>>  	Note that in non-bare repositories, reflogs are usually
>>  	enabled by default by the `core.logAllRefUpdates` config option.
>>  	The negated form `--no-create-reflog` only overrides an earlier
>> @@ -116,7 +116,7 @@ OPTIONS
>> 
>>  -f::
>>  --force::
>> -	Reset <branchname> to <start-point>, even if <branchname> exists
>> +	Reset <new-branch> to <start-point>, even if <new-branch> exists
>>  	already. Without `-f`, 'git branch' refuses to change an existing 
>> branch.
>>  	In combination with `-d` (or `--delete`), allow deleting the
>>  	branch irrespective of its merged status, or whether it even
>> @@ -124,8 +124,8 @@ OPTIONS
>>  	`-m` (or `--move`), allow renaming the branch even if the new
>>  	branch name already exists, the same applies for `-c` (or `--copy`).
>>  +
>> -Note that 'git branch -f <branchname> [<start-point>]', even with 
>> '-f',
>> -refuses to change an existing branch `<branchname>` that is checked 
>> out
>> +Note that 'git branch -f <new-branch> [<start-point>]', even with 
>> '-f',
>> +refuses to change an existing branch `<new-branch>` that is checked 
>> out
>>  in another worktree linked to the same repository.
>> 
>>  -m::
>> @@ -255,7 +255,7 @@ how the `branch.<name>.remote` and
>> `branch.<name>.merge` options are used.
>>  	linkgit:git-config[1]. Currently, only branch creation is
>>  	supported.
>>  +
>> -When used in branch creation, a new branch <branchname> will be 
>> created
>> +When used in branch creation, a new branch <new-branch> will be 
>> created
>>  in the superproject and all of the submodules in the superproject's
>>  <start-point>. In submodules, the branch will point to the submodule
>>  commit in the superproject's <start-point> but the branch's tracking
>> @@ -270,12 +270,12 @@ superproject's "origin/main", but tracks the
>> submodule's "origin/main".
>> 
>>  -u <upstream>::
>>  --set-upstream-to=<upstream>::
>> -	Set up <branchname>'s tracking information so <upstream> is
>> -	considered <branchname>'s upstream branch. If no <branchname>
>> +	Set up <branch>'s tracking information so <upstream> is
>> +	considered <branch>'s upstream branch. If no <branch>
>>  	is specified, then it defaults to the current branch.
>> 
>>  --unset-upstream::
>> -	Remove the upstream information for <branchname>. If no branch
>> +	Remove the upstream information for <branch>. If no branch
>>  	is specified it defaults to the current branch.
>> 
>>  --edit-description::
>> @@ -300,8 +300,8 @@ superproject's "origin/main", but tracks the
>> submodule's "origin/main".
>>  	Only list branches whose tips are not reachable from the
>>  	specified commit (HEAD if not specified). Implies `--list`.
>> 
>> -<branchname>::
>> -	The name of the branch to create or delete.
>> +<new-branch>::
>> +	The name of the branch to create.
>>  	The new branch name must pass all checks defined by
>>  	linkgit:git-check-ref-format[1].  Some of these checks
>>  	may restrict the characters allowed in a branch name.
>> @@ -311,14 +311,10 @@ superproject's "origin/main", but tracks the
>> submodule's "origin/main".
>>  	given as a branch name, a commit-id, or a tag.  If this
>>  	option is omitted, the current HEAD will be used instead.
>> 
>> -<oldbranch>::
>> +<branch>::
>>  	The name of an existing branch.  If this option is omitted,
>>  	the name of the current branch will be used instead.
>> 
>> -<newbranch>::
>> -	The new name for an existing branch. The same restrictions as for
>> -	<branchname> apply.
>> -
>>  --sort=<key>::
>>  	Sort based on the key given. Prefix `-` to sort in descending
>>  	order of the value. You may use the --sort=<key> option