[PATCH] branch: adjust documentation

From

Rubén Justo <rjusto@gmail.com>

Date

Feb 20, 2024, 20:25 UTC

Message-ID

<96f1afa6-f4ac-4593-9bf4-72dafe3cab85@gmail.com>

In-Reply-To

<16c1f883-881f-4f8c-95b2-22fb4825b733@gmail.com>

	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>
---

 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

-- 
2.44.0.rc2