From: Rubén Justo Date: Tue, 20 Feb 2024 19:12:16 GMT Subject: Re: [PATCH] branch: rework the descriptions of rename and copy operations Message-ID: <16c1f883-881f-4f8c-95b2-22fb4825b733@gmail.com> In-Reply-To: On 20-feb-2024 10:24:25, Junio C Hamano wrote: > I have slight aversion to non-words like "oldbranch" (not > "old-branch"), but not that much. I also have problems with . What's the reference in "old"? Prior to the restructuring of the whole file, we should probably do: ---- >8 --------- >8 --------- >8 --------- >8 ------ Subject: [PATCH] branch: adjust documentation Adjust the terms 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 | 57 +++++++++++++++++------------------- 1 file changed, 27 insertions(+), 30 deletions(-) diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index 0b08442932..d834d89a7f 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,24 +300,21 @@ 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 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. + If ommited, the current branch will be used instead. :: The new branch head will point to this commit. It may be 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. +:: + The name for new branch. The same restrictions as for + apply. --sort=:: Sort based on the key given. Prefix `-` to sort in descending -- 2.44.0.rc2