From: Jean-Noël Avila Date: Sun, 25 May 2025 20:27:09 +0000 (+0000) Subject: doc: convert git-switch manpage to new synopsis style X-Git-Tag: v2.50.0-rc1~8^2 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=b983aaabc8b8cf406686f23689dda7e226f67e44;p=thirdparty%2Fgit.git doc: convert git-switch manpage to new synopsis style - Switch the synopsis to a synopsis block which will automatically format placeholders in italics and keywords in monospace - Use __ instead of in the description - Use `backticks` for keywords and more complex option descriptions. The new rendering engine will apply synopsis rules to these spans. Signed-off-by: Jean-Noël Avila Signed-off-by: Junio C Hamano --- diff --git a/Documentation/git-switch.adoc b/Documentation/git-switch.adoc index f55315c51e..9f62abf9e2 100644 --- a/Documentation/git-switch.adoc +++ b/Documentation/git-switch.adoc @@ -7,11 +7,11 @@ git-switch - Switch branches SYNOPSIS -------- -[verse] -'git switch' [] [--no-guess] -'git switch' [] --detach [] -'git switch' [] (-c|-C) [] -'git switch' [] --orphan +[synopsis] +git switch [] [--no-guess] +git switch [] --detach [] +git switch [] (-c|-C) [] +git switch [] --orphan DESCRIPTION ----------- @@ -33,33 +33,33 @@ THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE. OPTIONS ------- -:: +__:: Branch to switch to. -:: +__:: Name for the new branch. -:: +__:: The starting point for the new branch. Specifying a - `` allows you to create a branch based on some - other point in history than where HEAD currently points. (Or, + __ allows you to create a branch based on some + other point in history than where `HEAD` currently points. (Or, in the case of `--detach`, allows you to inspect and detach from some other point.) + -You can use the `@{-N}` syntax to refer to the N-th last -branch/commit switched to using "git switch" or "git checkout" +You can use the `@{-}` syntax to refer to the __-th last +branch/commit switched to using `git switch` or `git checkout` operation. You may also specify `-` which is synonymous to `@{-1}`. This is often used to switch quickly between two branches, or to undo a branch switch by mistake. + -As a special case, you may use `A...B` as a shortcut for the merge -base of `A` and `B` if there is exactly one merge base. You can leave -out at most one of `A` and `B`, in which case it defaults to `HEAD`. - --c :: ---create :: - Create a new branch named `` starting at - `` before switching to the branch. This is the +As a special case, you may use `...` as a shortcut for the merge +base of __ and __ if there is exactly one merge base. You can leave +out at most one of __ and __, in which case it defaults to `HEAD`. + +`-c `:: +`--create `:: + Create a new branch named __ starting at + __ before switching to the branch. This is the transactional equivalent of + ------------ @@ -67,32 +67,32 @@ $ git branch $ git switch ------------ + -that is to say, the branch is not reset/created unless "git switch" is +that is to say, the branch is not reset/created unless `git switch` is successful (e.g., when the branch is in use in another worktree, not just the current branch stays the same, but the branch is not reset to the start-point, either). --C :: ---force-create :: - Similar to `--create` except that if `` already - exists, it will be reset to ``. This is a +`-C `:: +`--force-create `:: + Similar to `--create` except that if __ already + exists, it will be reset to __. This is a convenient shortcut for: + ------------ -$ git branch -f -$ git switch +$ git branch -f __ +$ git switch __ ------------ --d:: ---detach:: +`-d`:: +`--detach`:: Switch to a commit for inspection and discardable experiments. See the "DETACHED HEAD" section in linkgit:git-checkout[1] for details. ---guess:: ---no-guess:: - If `` is not found but there does exist a tracking - branch in exactly one remote (call it ``) with a +`--guess`:: +`--no-guess`:: + If __ is not found but there does exist a tracking + branch in exactly one remote (call it __) with a matching name, treat as equivalent to + ------------ @@ -101,9 +101,9 @@ $ git switch -c --track / + If the branch exists in multiple remotes and one of them is named by the `checkout.defaultRemote` configuration variable, we'll use that -one for the purposes of disambiguation, even if the `` isn't +one for the purposes of disambiguation, even if the __ isn't unique across all remotes. Set it to e.g. `checkout.defaultRemote=origin` -to always checkout remote branches from there if `` is +to always checkout remote branches from there if __ is ambiguous but exists on the 'origin' remote. See also `checkout.defaultRemote` in linkgit:git-config[1]. + @@ -112,19 +112,19 @@ ambiguous but exists on the 'origin' remote. See also The default behavior can be set via the `checkout.guess` configuration variable. --f:: ---force:: +`-f`:: +`--force`:: An alias for `--discard-changes`. ---discard-changes:: +`--discard-changes`:: Proceed even if the index or the working tree differs from `HEAD`. Both the index and working tree are restored to match the switching target. If `--recurse-submodules` is specified, submodule content is also restored to match the switching target. This is used to throw away local changes. --m:: ---merge:: +`-m`:: +`--merge`:: If you have local modifications to one or more files that are different between the current branch and the branch to which you are switching, the command refuses to switch branches in @@ -138,25 +138,25 @@ paths are left unmerged, and you need to resolve the conflicts and mark the resolved paths with `git add` (or `git rm` if the merge should result in deletion of the path). ---conflict=