From: Rubén Justo Date: Tue, 20 Feb 2024 20:25:56 GMT Subject: [PATCH] branch: adjust documentation Message-ID: <96f1afa6-f4ac-4593-9bf4-72dafe3cab85@gmail.com> In-Reply-To: <16c1f883-881f-4f8c-95b2-22fb4825b733@gmail.com> 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: --template= Best viewed with --word-diff. Signed-off-by: Rubén Justo --- 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] [...] 'git branch' [--track[=(direct|inherit)] | --no-track] [-f] - [--recurse-submodules] [] -'git branch' (--set-upstream-to= | -u ) [] -'git branch' --unset-upstream [] -'git branch' (-m | -M) [] -'git branch' (-c | -C) [] -'git branch' (-d | -D) [-r] ... -'git branch' --edit-description [] + [--recurse-submodules] [] +'git branch' (--set-upstream-to= | -u ) [] +'git branch' --unset-upstream [] +'git branch' (-m | -M) [] +'git branch' (-c | -C) [] +'git branch' (-d | -D) [-r] ... +'git branch' --edit-description [] DESCRIPTION ----------- @@ -53,7 +53,7 @@ branches not merged into the named commit will be listed. If the 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 +The command's second form creates a new branch head named which points to the current `HEAD`, or if given. As a special case, for , 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 " to switch to the +working tree to it; use "git switch " 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, will be renamed to . -If had a corresponding reflog, it is renamed to match -, and a reflog entry is created to remember the branch -renaming. If exists, -M must be used to force the rename +With a `-m` or `-M` option, will be renamed to . +If had a corresponding reflog, it is renamed to match +, and a reflog entry is created to remember the branch +renaming. If 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, `` will be deleted. You may +With a `-d` or `-D` option, `` 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 "@\{yesterday}". + based sha1 expressions such as "@\{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 to , even if exists + Reset to , even if 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 []', even with '-f', -refuses to change an existing branch `` that is checked out +Note that 'git branch -f []', even with '-f', +refuses to change an existing branch `` that is checked out in another worktree linked to the same repository. -m:: @@ -255,7 +255,7 @@ how the `branch..remote` and `branch..merge` options are used. linkgit:git-config[1]. Currently, only branch creation is supported. + -When used in branch creation, a new branch will be created +When used in branch creation, a new branch will be created in the superproject and all of the submodules in the superproject's . In submodules, the branch will point to the submodule commit in the superproject's but the branch's tracking @@ -270,12 +270,12 @@ superproject's "origin/main", but tracks the submodule's "origin/main". -u :: --set-upstream-to=:: - Set up 's tracking information so is - considered 's upstream branch. If no + Set up 's tracking information so is + considered 's upstream branch. If no is specified, then it defaults to the current branch. --unset-upstream:: - Remove the upstream information for . If no branch + Remove the upstream information for . 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`. -:: - The name of the branch to create or delete. +:: + 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. -:: +:: The name of an existing branch. If this option is omitted, the name of the current branch will be used instead. -:: - The new name for an existing branch. The same restrictions as for - apply. - --sort=:: Sort based on the key given. Prefix `-` to sort in descending order of the value. You may use the --sort= option -- 2.44.0.rc2