doc: apply new format to git-branch man page
- Switch the synopsis to a synopsis block which automatically formats 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 applies synopsis rules to these spans. Possible values for some variables, that were mentioned in the description prose, are now made into enumerated list. 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
Mar 19, 2025 at 08:16 UTC
7b399322a2ebbc720037c9524680390cc6354652
2 files changed
+196
-196
Documentation/config/branch.adoc
+53
-52
@@ -1,41 +1,42 @@
1
-branch.autoSetupMerge::
2
- Tells 'git branch', 'git switch' and 'git checkout' to set up new branches
1
+`branch.autoSetupMerge`::
2
+ Tells `git branch`, `git switch` and `git checkout` to set up new branches
3
so that linkgit:git-pull[1] will appropriately merge from the
4
starting point branch. Note that even if this option is not set,
5
this behavior can be chosen per-branch using the `--track`
6
- and `--no-track` options. The valid settings are: `false` -- no
7
- automatic setup is done; `true` -- automatic setup is done when the
8
- starting point is a remote-tracking branch; `always` --
9
- automatic setup is done when the starting point is either a
10
- local branch or remote-tracking branch; `inherit` -- if the starting point
11
- has a tracking configuration, it is copied to the new
12
- branch; `simple` -- automatic setup is done only when the starting point
6
+ and `--no-track` options. This option defaults to `true`. The valid settings
7
+ are:
8
+`false`;; no automatic setup is done
9
+`true`;; automatic setup is done when the starting point is a remote-tracking branch
10
+`always`;; automatic setup is done when the starting point is either a
11
+ local branch or remote-tracking branch
12
+`inherit`;; if the starting point has a tracking configuration, it is copied to the new
13
+ branch
14
+`simple`;; automatic setup is done only when the starting point
15
is a remote-tracking branch and the new branch has the same name as the
14
- remote branch. This option defaults to true.
16
+ remote branch.
17
16
-branch.autoSetupRebase::
17
- When a new branch is created with 'git branch', 'git switch' or 'git checkout'
18
+`branch.autoSetupRebase`::
19
+ When a new branch is created with `git branch`, `git switch` or `git checkout`
20
that tracks another branch, this variable tells Git to set
19
- up pull to rebase instead of merge (see "branch.<name>.rebase").
20
- When `never`, rebase is never automatically set to true.
21
- When `local`, rebase is set to true for tracked branches of
22
- other local branches.
23
- When `remote`, rebase is set to true for tracked branches of
24
- remote-tracking branches.
25
- When `always`, rebase will be set to true for all tracking
26
- branches.
27
- See "branch.autoSetupMerge" for details on how to set up a
28
- branch to track another branch.
29
- This option defaults to never.
21
+ up pull to rebase instead of merge (see `branch.<name>.rebase`).
22
+ The valid settings are:
23
+`never`;; rebase is never automatically set to true.
24
+`local`;; rebase is set to true for tracked branches of other local branches.
25
+`remote`;; rebase is set to true for tracked branches of remote-tracking branches.
26
+`always`;; rebase will be set to true for all tracking branches.
27
31
-branch.sort::
28
++
29
+See `branch.autoSetupMerge` for details on how to set up a branch to track another branch.
30
+This option defaults to `never`.
31
+
32
+`branch.sort`::
33
This variable controls the sort ordering of branches when displayed by
33
- linkgit:git-branch[1]. Without the "--sort=<value>" option provided, the
34
+ linkgit:git-branch[1]. Without the `--sort=<value>` option provided, the
35
value of this variable will be used as the default.
36
See linkgit:git-for-each-ref[1] field names for valid values.
37
37
-branch.<name>.remote::
38
- When on branch <name>, it tells 'git fetch' and 'git push'
38
+`branch.<name>.remote`::
39
+ When on branch _<name>_, it tells `git fetch` and `git push`
40
which remote to fetch from or push to. The remote to push to
41
may be overridden with `remote.pushDefault` (for all branches).
42
The remote to push to, for the current branch, may be further
@@ -46,58 +47,58 @@ branch.<name>.remote::
47
Additionally, `.` (a period) is the current local repository
48
(a dot-repository), see `branch.<name>.merge`'s final note below.
49
49
-branch.<name>.pushRemote::
50
- When on branch <name>, it overrides `branch.<name>.remote` for
50
+`branch.<name>.pushRemote`::
51
+ When on branch _<name>_, it overrides `branch.<name>.remote` for
52
pushing. It also overrides `remote.pushDefault` for pushing
52
- from branch <name>. When you pull from one place (e.g. your
53
+ from branch _<name>_. When you pull from one place (e.g. your
54
upstream) and push to another place (e.g. your own publishing
55
repository), you would want to set `remote.pushDefault` to
56
specify the remote to push to for all branches, and use this
57
option to override it for a specific branch.
58
58
-branch.<name>.merge::
59
- Defines, together with branch.<name>.remote, the upstream branch
60
- for the given branch. It tells 'git fetch'/'git pull'/'git rebase' which
61
- branch to merge and can also affect 'git push' (see push.default).
62
- When in branch <name>, it tells 'git fetch' the default
63
- refspec to be marked for merging in FETCH_HEAD. The value is
59
+`branch.<name>.merge`::
60
+ Defines, together with `branch.<name>.remote`, the upstream branch
61
+ for the given branch. It tells `git fetch`/`git pull`/`git rebase` which
62
+ branch to merge and can also affect `git push` (see `push.default`).
63
+ When in branch _<name>_, it tells `git fetch` the default
64
+ refspec to be marked for merging in `FETCH_HEAD`. The value is
65
handled like the remote part of a refspec, and must match a
66
ref which is fetched from the remote given by
66
- "branch.<name>.remote".
67
- The merge information is used by 'git pull' (which first calls
68
- 'git fetch') to lookup the default branch for merging. Without
69
- this option, 'git pull' defaults to merge the first refspec fetched.
67
+ `branch.<name>.remote`.
68
+ The merge information is used by `git pull` (which first calls
69
+ `git fetch`) to lookup the default branch for merging. Without
70
+ this option, `git pull` defaults to merge the first refspec fetched.
71
Specify multiple values to get an octopus merge.
71
- If you wish to setup 'git pull' so that it merges into <name> from
72
+ If you wish to setup `git pull` so that it merges into <name> from
73
another branch in the local repository, you can point
74
branch.<name>.merge to the desired branch, and use the relative path
74
- setting `.` (a period) for branch.<name>.remote.
75
+ setting `.` (a period) for `branch.<name>.remote`.
76
76
-branch.<name>.mergeOptions::
77
- Sets default options for merging into branch <name>. The syntax and
77
+`branch.<name>.mergeOptions`::
78
+ Sets default options for merging into branch _<name>_. The syntax and
79
supported options are the same as those of linkgit:git-merge[1], but
80
option values containing whitespace characters are currently not
81
supported.
82
82
-branch.<name>.rebase::
83
- When true, rebase the branch <name> on top of the fetched branch,
83
+`branch.<name>.rebase`::
84
+ When true, rebase the branch _<name>_ on top of the fetched branch,
85
instead of merging the default branch from the default remote when
85
- "git pull" is run. See "pull.rebase" for doing this in a non
86
+ `git pull` is run. See `pull.rebase` for doing this in a non
87
branch-specific manner.
88
+
88
-When `merges` (or just 'm'), pass the `--rebase-merges` option to 'git rebase'
89
+When `merges` (or just `m`), pass the `--rebase-merges` option to `git rebase`
90
so that the local merge commits are included in the rebase (see
91
linkgit:git-rebase[1] for details).
92
+
92
-When the value is `interactive` (or just 'i'), the rebase is run in interactive
93
+When the value is `interactive` (or just `i`), the rebase is run in interactive
94
mode.
95
+
96
*NOTE*: this is a possibly dangerous operation; do *not* use
97
it unless you understand the implications (see linkgit:git-rebase[1]
98
for details).
99
99
-branch.<name>.description::
100
+`branch.<name>.description`::
101
Branch description, can be edited with
102
`git branch --edit-description`. Branch description is
102
- automatically added to the format-patch cover letter or
103
- request-pull summary.
103
+ automatically added to the `format-patch` cover letter or
104
+ `request-pull` summary.
Documentation/git-branch.adoc
+143
-144
@@ -7,23 +7,23 @@ git-branch - List, create, or delete branches
7
8
SYNOPSIS
9
--------
10
-[verse]
11
-'git branch' [--color[=<when>] | --no-color] [--show-current]
12
- [-v [--abbrev=<n> | --no-abbrev]]
13
- [--column[=<options>] | --no-column] [--sort=<key>]
14
- [--merged [<commit>]] [--no-merged [<commit>]]
15
- [--contains [<commit>]] [--no-contains [<commit>]]
16
- [--points-at <object>] [--format=<format>]
17
- [(-r | --remotes) | (-a | --all)]
18
- [--list] [<pattern>...]
19
-'git branch' [--track[=(direct|inherit)] | --no-track] [-f]
20
- [--recurse-submodules] <branchname> [<start-point>]
21
-'git branch' (--set-upstream-to=<upstream> | -u <upstream>) [<branchname>]
22
-'git branch' --unset-upstream [<branchname>]
23
-'git branch' (-m | -M) [<oldbranch>] <newbranch>
24
-'git branch' (-c | -C) [<oldbranch>] <newbranch>
25
-'git branch' (-d | -D) [-r] <branchname>...
26
-'git branch' --edit-description [<branchname>]
10
+[synopsis]
11
+git branch [--color[=<when>] | --no-color] [--show-current]
12
+ [-v [--abbrev=<n> | --no-abbrev]]
13
+ [--column[=<options>] | --no-column] [--sort=<key>]
14
+ [--merged [<commit>]] [--no-merged [<commit>]]
15
+ [--contains [<commit>]] [--no-contains [<commit>]]
16
+ [--points-at <object>] [--format=<format>]
17
+ [(-r|--remotes) | (-a|--all)]
18
+ [--list] [<pattern>...]
19
+git branch [--track[=(direct|inherit)] | --no-track] [-f]
20
+ [--recurse-submodules] <branch-name> [<start-point>]
21
+git branch (--set-upstream-to=<upstream>|-u <upstream>) [<branch-name>]
22
+git branch --unset-upstream [<branch-name>]
23
+git branch (-m|-M) [<old-branch>] <new-branch>
24
+git branch (-c|-C) [<old-branch>] <new-branch>
25
+git branch (-d|-D) [-r] <branch-name>...
26
+git branch --edit-description [<branch-name>]
27
28
DESCRIPTION
29
-----------
@@ -49,173 +49,184 @@ With `--contains`, shows only the branches that contain the named commit
49
named commit), `--no-contains` inverts it. With `--merged`, only branches
50
merged into the named commit (i.e. the branches whose tip commits are
51
reachable from the named commit) will be listed. With `--no-merged` only
52
-branches not merged into the named commit will be listed. If the <commit>
52
+branches not merged into the named commit will be listed. If the _<commit>_
53
argument is missing it defaults to `HEAD` (i.e. the tip of the current
54
branch).
55
56
-The command's second form creates a new branch head named <branchname>
57
-which points to the current `HEAD`, or <start-point> if given. As a
58
-special case, for <start-point>, you may use `"A...B"` as a shortcut for
59
-the merge base of `A` and `B` if there is exactly one merge base. You
60
-can leave out at most one of `A` and `B`, in which case it defaults to
61
-`HEAD`.
56
+The command's second form creates a new branch head named _<branch-name>_
57
+which points to the current `HEAD`, or _<start-point>_ if given. As a
58
+special case, for _<start-point>_, you may use `<rev-A>...<rev-B>` as a
59
+shortcut for the merge base of _<rev-A>_ and _<rev-B>_ if there is exactly
60
+one merge base. You can leave out at most one of _<rev-A>_ and _<rev-B>_,
61
+in which case it defaults to `HEAD`.
62
63
Note that this will create the new branch, but it will not switch the
64
-working tree to it; use "git switch <newbranch>" to switch to the
64
+working tree to it; use `git switch <new-branch>` to switch to the
65
new branch.
66
67
When a local branch is started off a remote-tracking branch, Git sets up the
68
branch (specifically the `branch.<name>.remote` and `branch.<name>.merge`
69
-configuration entries) so that 'git pull' will appropriately merge from
69
+configuration entries) so that `git pull` will appropriately merge from
70
the remote-tracking branch. This behavior may be changed via the global
71
`branch.autoSetupMerge` configuration flag. That setting can be
72
overridden by using the `--track` and `--no-track` options, and
73
changed later using `git branch --set-upstream-to`.
74
75
-With a `-m` or `-M` option, <oldbranch> will be renamed to <newbranch>.
76
-If <oldbranch> had a corresponding reflog, it is renamed to match
77
-<newbranch>, and a reflog entry is created to remember the branch
78
-renaming. If <newbranch> exists, -M must be used to force the rename
75
+With a `-m` or `-M` option, _<old-branch>_ will be renamed to _<new-branch>_.
76
+If _<old-branch>_ had a corresponding reflog, it is renamed to match
77
+_<new-branch>_, and a reflog entry is created to remember the branch
78
+renaming. If _<new-branch>_ exists, `-M` must be used to force the rename
79
to happen.
80
81
The `-c` and `-C` options have the exact same semantics as `-m` and
82
`-M`, except instead of the branch being renamed, it will be copied to a
83
new name, along with its config and reflog.
84
85
-With a `-d` or `-D` option, `<branchname>` will be deleted. You may
85
+With a `-d` or `-D` option, _<branch-name>_ will be deleted. You may
86
specify more than one branch for deletion. If the branch currently
87
has a reflog then the reflog will also be deleted.
88
89
Use `-r` together with `-d` to delete remote-tracking branches. Note, that it
90
only makes sense to delete remote-tracking branches if they no longer exist
91
-in the remote repository or if 'git fetch' was configured not to fetch
92
-them again. See also the 'prune' subcommand of linkgit:git-remote[1] for a
91
+in the remote repository or if `git fetch` was configured not to fetch
92
+them again. See also the `prune` subcommand of linkgit:git-remote[1] for a
93
way to clean up all obsolete remote-tracking branches.
94
95
96
OPTIONS
97
-------
98
--d::
99
---delete::
98
+`-d`::
99
+`--delete`::
100
Delete a branch. The branch must be fully merged in its
101
upstream branch, or in `HEAD` if no upstream was set with
102
`--track` or `--set-upstream-to`.
103
104
--D::
104
+`-D`::
105
Shortcut for `--delete --force`.
106
107
---create-reflog::
107
+`--create-reflog`::
108
Create the branch's reflog. This activates recording of
109
all changes made to the branch ref, enabling use of date
110
- based sha1 expressions such as "<branchname>@\{yesterday}".
110
+ based sha1 expressions such as `<branch-name>@{yesterday}`.
111
Note that in non-bare repositories, reflogs are usually
112
enabled by default by the `core.logAllRefUpdates` config option.
113
The negated form `--no-create-reflog` only overrides an earlier
114
`--create-reflog`, but currently does not negate the setting of
115
`core.logAllRefUpdates`.
116
117
--f::
118
---force::
119
- Reset <branchname> to <start-point>, even if <branchname> exists
120
- already. Without `-f`, 'git branch' refuses to change an existing branch.
117
+`-f`::
118
+`--force`::
119
+ Reset _<branch-name>_ to _<start-point>_, even if _<branch-name>_ exists
120
+ already. Without `-f`, `git branch` refuses to change an existing branch.
121
In combination with `-d` (or `--delete`), allow deleting the
122
branch irrespective of its merged status, or whether it even
123
points to a valid commit. In combination with
124
`-m` (or `--move`), allow renaming the branch even if the new
125
branch name already exists, the same applies for `-c` (or `--copy`).
126
+
127
-Note that 'git branch -f <branchname> [<start-point>]', even with '-f',
128
-refuses to change an existing branch `<branchname>` that is checked out
127
+Note that `git branch -f <branch-name> [<start-point>]`, even with `-f`,
128
+refuses to change an existing branch _<branch-name>_ that is checked out
129
in another worktree linked to the same repository.
130
131
--m::
132
---move::
131
+`-m`::
132
+`--move`::
133
Move/rename a branch, together with its config and reflog.
134
135
--M::
135
+`-M`::
136
Shortcut for `--move --force`.
137
138
--c::
139
---copy::
138
+`-c`::
139
+`--copy`::
140
Copy a branch, together with its config and reflog.
141
142
--C::
142
+`-C`::
143
Shortcut for `--copy --force`.
144
145
---color[=<when>]::
145
+`--color[=<when>]`::
146
Color branches to highlight current, local, and
147
remote-tracking branches.
148
- The value must be always (the default), never, or auto.
148
+ The value must be `always` (the default), `never`, or `auto`.
149
150
---no-color::
150
+`--no-color`::
151
Turn off branch colors, even when the configuration file gives the
152
default to color output.
153
Same as `--color=never`.
154
155
--i::
156
---ignore-case::
155
+`-i`::
156
+`--ignore-case`::
157
Sorting and filtering branches are case insensitive.
158
159
---omit-empty::
159
+`--omit-empty`::
160
Do not print a newline after formatted refs where the format expands
161
to the empty string.
162
163
---column[=<options>]::
164
---no-column::
163
+`--column[=<options>]`::
164
+`--no-column`::
165
Display branch listing in columns. See configuration variable
166
`column.branch` for option syntax. `--column` and `--no-column`
167
- without options are equivalent to 'always' and 'never' respectively.
167
+ without options are equivalent to `always` and `never` respectively.
168
+
169
This option is only applicable in non-verbose mode.
170
171
--r::
172
---remotes::
173
- List or delete (if used with -d) the remote-tracking branches.
171
+`--sort=<key>`::
172
+ Sort based on _<key>_. Prefix `-` to sort in descending
173
+ order of the value. You may use the `--sort=<key>` option
174
+ multiple times, in which case the last key becomes the primary
175
+ key. The keys supported are the same as those in linkgit:git-for-each-ref[1].
176
+ Sort order defaults to the value configured for the
177
+ `branch.sort` variable if it exists, or to sorting based on the
178
+ full refname (including `refs/...` prefix). This lists
179
+ detached `HEAD` (if present) first, then local branches and
180
+ finally remote-tracking branches. See linkgit:git-config[1].
181
+
182
+`-r`::
183
+`--remotes`::
184
+ List or delete (if used with `-d`) the remote-tracking branches.
185
Combine with `--list` to match the optional pattern(s).
186
176
--a::
177
---all::
187
+`-a`::
188
+`--all`::
189
List both remote-tracking branches and local branches.
190
Combine with `--list` to match optional pattern(s).
191
181
--l::
182
---list::
192
+`-l`::
193
+`--list`::
194
List branches. With optional `<pattern>...`, e.g. `git
195
branch --list 'maint-*'`, list only the branches that match
196
the pattern(s).
197
187
---show-current::
188
- Print the name of the current branch. In detached HEAD state,
198
+`--show-current`::
199
+ Print the name of the current branch. In detached `HEAD` state,
200
nothing is printed.
201
191
--v::
192
--vv::
193
---verbose::
202
+`-v`::
203
+`-vv`::
204
+`--verbose`::
205
When in list mode,
206
show sha1 and commit subject line for each head, along with
207
relationship to upstream branch (if any). If given twice, print
208
the path of the linked worktree (if any) and the name of the upstream
209
branch, as well (see also `git remote show <remote>`). Note that the
199
- current worktree's HEAD will not have its path printed (it will always
210
+ current worktree's `HEAD` will not have its path printed (it will always
211
be your current directory).
212
202
--q::
203
---quiet::
213
+`-q`::
214
+`--quiet`::
215
Be more quiet when creating or deleting a branch, suppressing
216
non-error messages.
217
207
---abbrev=<n>::
218
+`--abbrev=<n>`::
219
In the verbose listing that show the commit object name,
209
- show the shortest prefix that is at least '<n>' hexdigits
220
+ show the shortest prefix that is at least _<n>_ hexdigits
221
long that uniquely refers the object.
222
The default value is 7 and can be overridden by the `core.abbrev`
223
config option.
224
214
---no-abbrev::
225
+`--no-abbrev`::
226
Display the full sha1s in the output listing rather than abbreviating them.
227
217
--t::
218
---track[=(direct|inherit)]::
228
+`-t`::
229
+`--track[=(direct|inherit)]`::
230
When creating a new branch, set up `branch.<name>.remote` and
231
`branch.<name>.merge` configuration entries to set "upstream" tracking
232
configuration for the new branch. This
@@ -229,7 +240,7 @@ The exact upstream branch is chosen depending on the optional argument:
240
itself as the upstream; `--track=inherit` means to copy the upstream
241
configuration of the start-point branch.
242
+
232
-The branch.autoSetupMerge configuration variable specifies how `git switch`,
243
+The `branch.autoSetupMerge` configuration variable specifies how `git switch`,
244
`git checkout` and `git branch` should behave when neither `--track` nor
245
`--no-track` are specified:
246
+
@@ -238,106 +249,94 @@ were given whenever the start-point is a remote-tracking branch.
249
`false` behaves as if `--no-track` were given. `always` behaves as though
250
`--track=direct` were given. `inherit` behaves as though `--track=inherit`
251
were given. `simple` behaves as though `--track=direct` were given only when
241
-the start-point is a remote-tracking branch and the new branch has the same
252
+the _<start-point>_ is a remote-tracking branch and the new branch has the same
253
name as the remote branch.
254
+
255
See linkgit:git-pull[1] and linkgit:git-config[1] for additional discussion on
256
how the `branch.<name>.remote` and `branch.<name>.merge` options are used.
257
247
---no-track::
258
+`--no-track`::
259
Do not set up "upstream" configuration, even if the
249
- branch.autoSetupMerge configuration variable is set.
260
+ `branch.autoSetupMerge` configuration variable is set.
261
251
---recurse-submodules::
252
- THIS OPTION IS EXPERIMENTAL! Causes the current command to
262
+`--recurse-submodules`::
263
+ THIS OPTION IS EXPERIMENTAL! Cause the current command to
264
recurse into submodules if `submodule.propagateBranches` is
265
enabled. See `submodule.propagateBranches` in
266
linkgit:git-config[1]. Currently, only branch creation is
267
supported.
268
+
258
-When used in branch creation, a new branch <branchname> will be created
269
+When used in branch creation, a new branch _<branch-name>_ will be created
270
in the superproject and all of the submodules in the superproject's
260
-<start-point>. In submodules, the branch will point to the submodule
261
-commit in the superproject's <start-point> but the branch's tracking
271
+_<start-point>_. In submodules, the branch will point to the submodule
272
+commit in the superproject's _<start-point>_ but the branch's tracking
273
information will be set up based on the submodule's branches and remotes
274
e.g. `git branch --recurse-submodules topic origin/main` will create the
275
submodule branch "topic" that points to the submodule commit in the
276
superproject's "origin/main", but tracks the submodule's "origin/main".
277
267
---set-upstream::
278
+`--set-upstream`::
279
As this option had confusing syntax, it is no longer supported.
280
Please use `--track` or `--set-upstream-to` instead.
281
271
--u <upstream>::
272
---set-upstream-to=<upstream>::
273
- Set up <branchname>'s tracking information so <upstream> is
274
- considered <branchname>'s upstream branch. If no <branchname>
282
+`-u <upstream>`::
283
+`--set-upstream-to=<upstream>`::
284
+ Set up _<branch-name>_'s tracking information so _<upstream>_ is
285
+ considered _<branch-name>_'s upstream branch. If no _<branch-name>_
286
is specified, then it defaults to the current branch.
287
277
---unset-upstream::
278
- Remove the upstream information for <branchname>. If no branch
288
+`--unset-upstream`::
289
+ Remove the upstream information for _<branch-name>_. If no branch
290
is specified it defaults to the current branch.
291
281
---edit-description::
292
+`--edit-description`::
293
Open an editor and edit the text to explain what the branch is
294
for, to be used by various other commands (e.g. `format-patch`,
295
`request-pull`, and `merge` (if enabled)). Multi-line explanations
296
may be used.
297
287
---contains [<commit>]::
288
- Only list branches which contain the specified commit (HEAD
298
+`--contains [<commit>]`::
299
+ Only list branches which contain _<commit>_ (`HEAD`
300
if not specified). Implies `--list`.
301
291
---no-contains [<commit>]::
292
- Only list branches which don't contain the specified commit
293
- (HEAD if not specified). Implies `--list`.
302
+`--no-contains [<commit>]`::
303
+ Only list branches which don't contain _<commit>_
304
+ (`HEAD` if not specified). Implies `--list`.
305
295
---merged [<commit>]::
296
- Only list branches whose tips are reachable from the
297
- specified commit (HEAD if not specified). Implies `--list`.
306
+`--merged [<commit>]`::
307
+ Only list branches whose tips are reachable from
308
+ _<commit>_ (`HEAD` if not specified). Implies `--list`.
309
299
---no-merged [<commit>]::
300
- Only list branches whose tips are not reachable from the
301
- specified commit (HEAD if not specified). Implies `--list`.
310
+`--no-merged [<commit>]`::
311
+ Only list branches whose tips are not reachable from
312
+ _<commit>_ (`HEAD` if not specified). Implies `--list`.
313
303
-<branchname>::
314
+`--points-at <object>`::
315
+ Only list branches of _<object>_.
316
+
317
+`--format <format>`::
318
+ A string that interpolates `%(fieldname)` from a branch ref being shown
319
+ and the object it points at. _<format>_ is the same as
320
+ that of linkgit:git-for-each-ref[1].
321
+
322
+_<branch-name>_::
323
The name of the branch to create or delete.
324
The new branch name must pass all checks defined by
325
linkgit:git-check-ref-format[1]. Some of these checks
326
may restrict the characters allowed in a branch name.
327
309
-<start-point>::
328
+_<start-point>_::
329
The new branch head will point to this commit. It may be
330
given as a branch name, a commit-id, or a tag. If this
312
- option is omitted, the current HEAD will be used instead.
331
+ option is omitted, the current `HEAD` will be used instead.
332
314
-<oldbranch>::
333
+_<old-branch>_::
334
The name of an existing branch. If this option is omitted,
335
the name of the current branch will be used instead.
336
318
-<newbranch>::
337
+_<new-branch>_::
338
The new name for an existing branch. The same restrictions as for
320
- <branchname> apply.
321
-
322
---sort=<key>::
323
- Sort based on the key given. Prefix `-` to sort in descending
324
- order of the value. You may use the --sort=<key> option
325
- multiple times, in which case the last key becomes the primary
326
- key. The keys supported are the same as those in `git
327
- for-each-ref`. Sort order defaults to the value configured for the
328
- `branch.sort` variable if it exists, or to sorting based on the
329
- full refname (including `refs/...` prefix). This lists
330
- detached HEAD (if present) first, then local branches and
331
- finally remote-tracking branches. See linkgit:git-config[1].
332
-
333
-
334
---points-at <object>::
335
- Only list branches of the given object.
336
-
337
---format <format>::
338
- A string that interpolates `%(fieldname)` from a branch ref being shown
339
- and the object it points at. The format is the same as
340
- that of linkgit:git-for-each-ref[1].
339
+ _<branch-name>_ apply.
340
341
CONFIGURATION
342
-------------
@@ -374,7 +373,7 @@ $ git branch -D test <2>
373
------------
374
+
375
<1> Delete the remote-tracking branches "todo", "html" and "man". The next
377
- 'fetch' or 'pull' will create them again unless you configure them not to.
376
+ `git fetch` or `git pullè will create them again unless you configure them not to.
377
See linkgit:git-fetch[1].
378
<2> Delete the "test" branch even if the "master" branch (or whichever branch
379
is currently checked out) does not have all commits from the test branch.
@@ -386,8 +385,8 @@ $ git branch -r -l '<remote>/<pattern>' <1>
385
$ git for-each-ref 'refs/remotes/<remote>/<pattern>' <2>
386
------------
387
+
389
-<1> Using `-a` would conflate <remote> with any local branches you happen to
390
- have been prefixed with the same <remote> pattern.
388
+<1> Using `-a` would conflate _<remote>_ with any local branches you happen to
389
+ have been prefixed with the same _<remote>_ pattern.
390
<2> `for-each-ref` can take a wide range of options. See linkgit:git-for-each-ref[1]
391
392
Patterns will normally need quoting.
@@ -396,24 +395,24 @@ NOTES
395
-----
396
397
If you are creating a branch that you want to switch to immediately,
399
-it is easier to use the "git switch" command with its `-c` option to
398
+it is easier to use the `git switch` command with its `-c` option to
399
do the same thing with a single command.
400
401
The options `--contains`, `--no-contains`, `--merged` and `--no-merged`
402
serve four related but different purposes:
403
404
- `--contains <commit>` is used to find all branches which will need
406
- special attention if <commit> were to be rebased or amended, since those
407
- branches contain the specified <commit>.
405
+ special attention if _<commit>_ were to be rebased or amended, since those
406
+ branches contain the specified _<commit>_.
407
408
- `--no-contains <commit>` is the inverse of that, i.e. branches that don't
410
- contain the specified <commit>.
409
+ contain the specified _<commit>_.
410
411
- `--merged` is used to find all branches which can be safely deleted,
413
- since those branches are fully contained by HEAD.
412
+ since those branches are fully contained by `HEAD`.
413
414
- `--no-merged` is used to find branches which are candidates for merging
416
- into HEAD, since those branches are not fully contained by HEAD.
415
+ into `HEAD`, since those branches are not fully contained by `HEAD`.
416
417
include::ref-reachability-filters.adoc[]
418
@@ -422,8 +421,8 @@ SEE ALSO
421
linkgit:git-check-ref-format[1],
422
linkgit:git-fetch[1],
423
linkgit:git-remote[1],
425
-link:user-manual.html#what-is-a-branch[``Understanding history: What is
426
-a branch?''] in the Git User's Manual.
424
+link:user-manual.html#what-is-a-branch["Understanding history: What is
425
+a branch?"] in the Git User's Manual.
426
427
GIT
428
---