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 _<placeholder>_ instead of <placeholder> 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 <jn.avila@free.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Jean-Noël Avila committed
May 25, 2025 at 20:27 UTC
b983aaabc8b8cf406686f23689dda7e226f67e44
1 file changed
+57
-57
Documentation/git-switch.adoc
+57
-57
@@ -7,11 +7,11 @@ git-switch - Switch branches
7
8
SYNOPSIS
9
--------
10
-[verse]
11
-'git switch' [<options>] [--no-guess] <branch>
12
-'git switch' [<options>] --detach [<start-point>]
13
-'git switch' [<options>] (-c|-C) <new-branch> [<start-point>]
14
-'git switch' [<options>] --orphan <new-branch>
10
+[synopsis]
11
+git switch [<options>] [--no-guess] <branch>
12
+git switch [<options>] --detach [<start-point>]
13
+git switch [<options>] (-c|-C) <new-branch> [<start-point>]
14
+git switch [<options>] --orphan <new-branch>
15
16
DESCRIPTION
17
-----------
@@ -33,33 +33,33 @@ THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE.
33
34
OPTIONS
35
-------
36
-<branch>::
36
+_<branch>_::
37
Branch to switch to.
38
39
-<new-branch>::
39
+_<new-branch>_::
40
Name for the new branch.
41
42
-<start-point>::
42
+_<start-point>_::
43
The starting point for the new branch. Specifying a
44
- `<start-point>` allows you to create a branch based on some
45
- other point in history than where HEAD currently points. (Or,
44
+ _<start-point>_ allows you to create a branch based on some
45
+ other point in history than where `HEAD` currently points. (Or,
46
in the case of `--detach`, allows you to inspect and detach
47
from some other point.)
48
+
49
-You can use the `@{-N}` syntax to refer to the N-th last
50
-branch/commit switched to using "git switch" or "git checkout"
49
+You can use the `@{-<N>}` syntax to refer to the _<N>_-th last
50
+branch/commit switched to using `git switch` or `git checkout`
51
operation. You may also specify `-` which is synonymous to `@{-1}`.
52
This is often used to switch quickly between two branches, or to undo
53
a branch switch by mistake.
54
+
55
-As a special case, you may use `A...B` as a shortcut for the merge
56
-base of `A` and `B` if there is exactly one merge base. You can leave
57
-out at most one of `A` and `B`, in which case it defaults to `HEAD`.
58
-
59
--c <new-branch>::
60
---create <new-branch>::
61
- Create a new branch named `<new-branch>` starting at
62
- `<start-point>` before switching to the branch. This is the
55
+As a special case, you may use `<rev-a>...<rev-b>` as a shortcut for the merge
56
+base of _<rev-a>_ and _<rev-b>_ if there is exactly one merge base. You can leave
57
+out at most one of _<rev-a>_ and _<rev-b>_, in which case it defaults to `HEAD`.
58
+
59
+`-c <new-branch>`::
60
+`--create <new-branch>`::
61
+ Create a new branch named _<new-branch>_ starting at
62
+ _<start-point>_ before switching to the branch. This is the
63
transactional equivalent of
64
+
65
------------
@@ -67,32 +67,32 @@ $ git branch <new-branch>
67
$ git switch <new-branch>
68
------------
69
+
70
-that is to say, the branch is not reset/created unless "git switch" is
70
+that is to say, the branch is not reset/created unless `git switch` is
71
successful (e.g., when the branch is in use in another worktree, not
72
just the current branch stays the same, but the branch is not reset to
73
the start-point, either).
74
75
--C <new-branch>::
76
---force-create <new-branch>::
77
- Similar to `--create` except that if `<new-branch>` already
78
- exists, it will be reset to `<start-point>`. This is a
75
+`-C <new-branch>`::
76
+`--force-create <new-branch>`::
77
+ Similar to `--create` except that if _<new-branch>_ already
78
+ exists, it will be reset to _<start-point>_. This is a
79
convenient shortcut for:
80
+
81
------------
82
-$ git branch -f <new-branch>
83
-$ git switch <new-branch>
82
+$ git branch -f _<new-branch>_
83
+$ git switch _<new-branch>_
84
------------
85
86
--d::
87
---detach::
86
+`-d`::
87
+`--detach`::
88
Switch to a commit for inspection and discardable
89
experiments. See the "DETACHED HEAD" section in
90
linkgit:git-checkout[1] for details.
91
92
---guess::
93
---no-guess::
94
- If `<branch>` is not found but there does exist a tracking
95
- branch in exactly one remote (call it `<remote>`) with a
92
+`--guess`::
93
+`--no-guess`::
94
+ If _<branch>_ is not found but there does exist a tracking
95
+ branch in exactly one remote (call it _<remote>_) with a
96
matching name, treat as equivalent to
97
+
98
------------
@@ -101,9 +101,9 @@ $ git switch -c <branch> --track <remote>/<branch>
101
+
102
If the branch exists in multiple remotes and one of them is named by
103
the `checkout.defaultRemote` configuration variable, we'll use that
104
-one for the purposes of disambiguation, even if the `<branch>` isn't
104
+one for the purposes of disambiguation, even if the _<branch>_ isn't
105
unique across all remotes. Set it to e.g. `checkout.defaultRemote=origin`
106
-to always checkout remote branches from there if `<branch>` is
106
+to always checkout remote branches from there if _<branch>_ is
107
ambiguous but exists on the 'origin' remote. See also
108
`checkout.defaultRemote` in linkgit:git-config[1].
109
+
@@ -112,19 +112,19 @@ ambiguous but exists on the 'origin' remote. See also
112
The default behavior can be set via the `checkout.guess` configuration
113
variable.
114
115
--f::
116
---force::
115
+`-f`::
116
+`--force`::
117
An alias for `--discard-changes`.
118
119
---discard-changes::
119
+`--discard-changes`::
120
Proceed even if the index or the working tree differs from
121
`HEAD`. Both the index and working tree are restored to match
122
the switching target. If `--recurse-submodules` is specified,
123
submodule content is also restored to match the switching
124
target. This is used to throw away local changes.
125
126
--m::
127
---merge::
126
+`-m`::
127
+`--merge`::
128
If you have local modifications to one or more files that are
129
different between the current branch and the branch to which
130
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
138
and mark the resolved paths with `git add` (or `git rm` if the merge
139
should result in deletion of the path).
140
141
---conflict=<style>::
141
+`--conflict=<style>`::
142
The same as `--merge` option above, but changes the way the
143
conflicting hunks are presented, overriding the
144
`merge.conflictStyle` configuration variable. Possible values are
145
- "merge" (default), "diff3", and "zdiff3".
145
+ `merge` (default), `diff3`, and `zdiff3`.
146
147
--q::
148
---quiet::
147
+`-q`::
148
+`--quiet`::
149
Quiet, suppress feedback messages.
150
151
---progress::
152
---no-progress::
151
+`--progress`::
152
+`--no-progress`::
153
Progress status is reported on the standard error stream
154
by default when it is attached to a terminal, unless `--quiet`
155
is specified. This flag enables progress reporting even if not
156
attached to a terminal, regardless of `--quiet`.
157
158
--t::
159
---track [direct|inherit]::
158
+`-t`::
159
+`--track[ (direct|inherit)]`::
160
When creating a new branch, set up "upstream" configuration.
161
`-c` is implied. See `--track` in linkgit:git-branch[1] for
162
details.
@@ -171,22 +171,22 @@ given name has no slash, or the above guessing results in an empty
171
name, the guessing is aborted. You can explicitly give a name with
172
`-c` in such a case.
173
174
---no-track::
174
+`--no-track`::
175
Do not set up "upstream" configuration, even if the
176
`branch.autoSetupMerge` configuration variable is true.
177
178
---orphan <new-branch>::
179
- Create a new unborn branch, named `<new-branch>`. All
178
+`--orphan <new-branch>`::
179
+ Create a new unborn branch, named _<new-branch>_. All
180
tracked files are removed.
181
182
---ignore-other-worktrees::
182
+`--ignore-other-worktrees`::
183
`git switch` refuses when the wanted ref is already
184
checked out by another worktree. This option makes it check
185
the ref out anyway. In other words, the ref can be held by
186
more than one worktree.
187
188
---recurse-submodules::
189
---no-recurse-submodules::
188
+`--recurse-submodules`::
189
+`--no-recurse-submodules`::
190
Using `--recurse-submodules` will update the content of all
191
active submodules according to the commit recorded in the
192
superproject. If nothing (or `--no-recurse-submodules`) is
@@ -239,7 +239,7 @@ $ git switch -
239
------------
240
241
You can grow a new branch from any commit. For example, switch to
242
-"HEAD~3" and create branch "fixup":
242
+"`HEAD~3`" and create branch "`fixup`":
243
244
------------
245
$ git switch -c fixup HEAD~3
@@ -251,8 +251,8 @@ name:
251
252
------------
253
$ git switch new-topic
254
-Branch 'new-topic' set up to track remote branch 'new-topic' from 'origin'
255
-Switched to a new branch 'new-topic'
254
+Branch `new-topic` set up to track remote branch `new-topic` from `origin`
255
+Switched to a new branch `new-topic`
256
------------
257
258
To check out commit `HEAD~3` for temporary inspection or experiment