freshlybakedca.ke
Git fork
1git-branch(1)
2=============
3
4NAME
5----
6git-branch - List, create, or delete branches
7
8SYNOPSIS
9--------
10[synopsis]
11git 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>...]
19git branch [--track[=(direct|inherit)] | --no-track] [-f]
20 [--recurse-submodules] <branch-name> [<start-point>]
21git branch (--set-upstream-to=<upstream>|-u <upstream>) [<branch-name>]
22git branch --unset-upstream [<branch-name>]
23git branch (-m|-M) [<old-branch>] <new-branch>
24git branch (-c|-C) [<old-branch>] <new-branch>
25git branch (-d|-D) [-r] <branch-name>...
26git branch --edit-description [<branch-name>]
27
28DESCRIPTION
29-----------
30
31If `--list` is given, or if there are no non-option arguments, existing
32branches are listed; the current branch will be highlighted in green and
33marked with an asterisk. Any branches checked out in linked worktrees will
34be highlighted in cyan and marked with a plus sign. Option `-r` causes the
35remote-tracking branches to be listed,
36and option `-a` shows both local and remote branches.
37
38If a `<pattern>`
39is given, it is used as a shell wildcard to restrict the output to
40matching branches. If multiple patterns are given, a branch is shown if
41it matches any of the patterns.
42
43Note that when providing a
44`<pattern>`, you must use `--list`; otherwise the command may be interpreted
45as branch creation.
46
47With `--contains`, shows only the branches that contain the named commit
48(in other words, the branches whose tip commits are descendants of the
49named commit), `--no-contains` inverts it. With `--merged`, only branches
50merged into the named commit (i.e. the branches whose tip commits are
51reachable from the named commit) will be listed. With `--no-merged` only
52branches not merged into the named commit will be listed. If the _<commit>_
53argument is missing it defaults to `HEAD` (i.e. the tip of the current
54branch).
55
56The command's second form creates a new branch head named _<branch-name>_
57which points to the current `HEAD`, or _<start-point>_ if given. As a
58special case, for _<start-point>_, you may use `<rev-A>...<rev-B>` as a
59shortcut for the merge base of _<rev-A>_ and _<rev-B>_ if there is exactly
60one merge base. You can leave out at most one of _<rev-A>_ and _<rev-B>_,
61in which case it defaults to `HEAD`.
62
63Note that this will create the new branch, but it will not switch the
64working tree to it; use `git switch <new-branch>` to switch to the
65new branch.
66
67When a local branch is started off a remote-tracking branch, Git sets up the
68branch (specifically the `branch.<name>.remote` and `branch.<name>.merge`
69configuration entries) so that `git pull` will appropriately merge from
70the remote-tracking branch. This behavior may be changed via the global
71`branch.autoSetupMerge` configuration flag. That setting can be
72overridden by using the `--track` and `--no-track` options, and
73changed later using `git branch --set-upstream-to`.
74
75With a `-m` or `-M` option, _<old-branch>_ will be renamed to _<new-branch>_.
76If _<old-branch>_ had a corresponding reflog, it is renamed to match
77_<new-branch>_, and a reflog entry is created to remember the branch
78renaming. If _<new-branch>_ exists, `-M` must be used to force the rename
79to happen.
80
81The `-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
83new name, along with its config and reflog.
84
85With a `-d` or `-D` option, _<branch-name>_ will be deleted. You may
86specify more than one branch for deletion. If the branch currently
87has a reflog then the reflog will also be deleted.
88
89Use `-r` together with `-d` to delete remote-tracking branches. Note, that it
90only makes sense to delete remote-tracking branches if they no longer exist
91in the remote repository or if `git fetch` was configured not to fetch
92them again. See also the `prune` subcommand of linkgit:git-remote[1] for a
93way to clean up all obsolete remote-tracking branches.
94
95
96OPTIONS
97-------
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`::
105 Shortcut for `--delete --force`.
106
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 `<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 _<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+
127Note that `git branch -f <branch-name> [<start-point>]`, even with `-f`,
128refuses to change an existing branch _<branch-name>_ that is checked out
129in another worktree linked to the same repository.
130
131`-m`::
132`--move`::
133 Move/rename a branch, together with its config and reflog.
134
135`-M`::
136 Shortcut for `--move --force`.
137
138`-c`::
139`--copy`::
140 Copy a branch, together with its config and reflog.
141
142`-C`::
143 Shortcut for `--copy --force`.
144
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`.
149
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`::
157 Sorting and filtering branches are case insensitive.
158
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`::
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.
168+
169This option is only applicable in non-verbose mode.
170
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
187`-a`::
188`--all`::
189 List both remote-tracking branches and local branches.
190 Combine with `--list` to match optional pattern(s).
191
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
198`--show-current`::
199 Print the name of the current branch. In detached `HEAD` state,
200 nothing is printed.
201
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
210 current worktree's `HEAD` will not have its path printed (it will always
211 be your current directory).
212
213`-q`::
214`--quiet`::
215 Be more quiet when creating or deleting a branch, suppressing
216 non-error messages.
217
218`--abbrev=<n>`::
219 In the verbose listing that show the commit object name,
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
225`--no-abbrev`::
226 Display the full sha1s in the output listing rather than abbreviating them.
227
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
233 configuration will tell git to show the relationship between the
234 two branches in `git status` and `git branch -v`. Furthermore,
235 it directs `git pull` without arguments to pull from the
236 upstream when the new branch is checked out.
237+
238The exact upstream branch is chosen depending on the optional argument:
239`-t`, `--track`, or `--track=direct` means to use the start-point branch
240itself as the upstream; `--track=inherit` means to copy the upstream
241configuration of the start-point branch.
242+
243The `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+
247The default option, `true`, behaves as though `--track=direct`
248were 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`
251were given. `simple` behaves as though `--track=direct` were given only when
252the _<start-point>_ is a remote-tracking branch and the new branch has the same
253name as the remote branch.
254+
255See linkgit:git-pull[1] and linkgit:git-config[1] for additional discussion on
256how the `branch.<name>.remote` and `branch.<name>.merge` options are used.
257
258`--no-track`::
259 Do not set up "upstream" configuration, even if the
260 `branch.autoSetupMerge` configuration variable is set.
261
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+
269When used in branch creation, a new branch _<branch-name>_ will be created
270in the superproject and all of the submodules in the superproject's
271_<start-point>_. In submodules, the branch will point to the submodule
272commit in the superproject's _<start-point>_ but the branch's tracking
273information will be set up based on the submodule's branches and remotes
274e.g. `git branch --recurse-submodules topic origin/main` will create the
275submodule branch "topic" that points to the submodule commit in the
276superproject's "origin/main", but tracks the submodule's "origin/main".
277
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
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
288`--unset-upstream`::
289 Remove the upstream information for _<branch-name>_. If no branch
290 is specified it defaults to the current branch.
291
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
298`--contains [<commit>]`::
299 Only list branches which contain _<commit>_ (`HEAD`
300 if not specified). Implies `--list`.
301
302`--no-contains [<commit>]`::
303 Only list branches which don't contain _<commit>_
304 (`HEAD` if not specified). Implies `--list`.
305
306`--merged [<commit>]`::
307 Only list branches whose tips are reachable from
308 _<commit>_ (`HEAD` if not specified). Implies `--list`.
309
310`--no-merged [<commit>]`::
311 Only list branches whose tips are not reachable from
312 _<commit>_ (`HEAD` if not specified). Implies `--list`.
313
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
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
331 option is omitted, the current `HEAD` will be used instead.
332
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
337_<new-branch>_::
338 The new name for an existing branch. The same restrictions as for
339 _<branch-name>_ apply.
340
341CONFIGURATION
342-------------
343`pager.branch` is only respected when listing branches, i.e., when
344`--list` is used or implied. The default is to use a pager.
345See linkgit:git-config[1].
346
347include::includes/cmd-config-section-rest.adoc[]
348
349include::config/branch.adoc[]
350
351EXAMPLES
352--------
353
354Start development from a known tag::
355+
356------------
357$ git clone git://git.kernel.org/pub/scm/.../linux-2.6 my2.6
358$ cd my2.6
359$ git branch my2.6.14 v2.6.14 <1>
360$ git switch my2.6.14
361------------
362+
363<1> This step and the next one could be combined into a single step with
364 "checkout -b my2.6.14 v2.6.14".
365
366Delete an unneeded branch::
367+
368------------
369$ git clone git://git.kernel.org/.../git.git my.git
370$ cd my.git
371$ git branch -d -r origin/todo origin/html origin/man <1>
372$ git branch -D test <2>
373------------
374+
375<1> Delete the remote-tracking branches "todo", "html" and "man". The next
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.
380
381Listing branches from a specific remote::
382+
383------------
384$ git branch -r -l '<remote>/<pattern>' <1>
385$ git for-each-ref 'refs/remotes/<remote>/<pattern>' <2>
386------------
387+
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
392Patterns will normally need quoting.
393
394NOTES
395-----
396
397If you are creating a branch that you want to switch to immediately,
398it is easier to use the `git switch` command with its `-c` option to
399do the same thing with a single command.
400
401The options `--contains`, `--no-contains`, `--merged` and `--no-merged`
402serve four related but different purposes:
403
404- `--contains <commit>` is used to find all branches which will need
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
409 contain the specified _<commit>_.
410
411- `--merged` is used to find all branches which can be safely deleted,
412 since those branches are fully contained by `HEAD`.
413
414- `--no-merged` is used to find branches which are candidates for merging
415 into `HEAD`, since those branches are not fully contained by `HEAD`.
416
417include::ref-reachability-filters.adoc[]
418
419SEE ALSO
420--------
421linkgit:git-check-ref-format[1],
422linkgit:git-fetch[1],
423linkgit:git-remote[1],
424link:user-manual.html#what-is-a-branch["Understanding history: What is
425a branch?"] in the Git User's Manual.
426
427GIT
428---
429Part of the linkgit:git[1] suite