1GIT-BRANCH(1)                     Git Manual                     GIT-BRANCH(1)
2
3
4

NAME

6       git-branch - List, create, or delete branches
7

SYNOPSIS

9       git branch [--color[=<when>] | --no-color] [--show-current]
10               [-v [--abbrev=<n> | --no-abbrev]]
11               [--column[=<options>] | --no-column] [--sort=<key>]
12               [--merged [<commit>]] [--no-merged [<commit>]]
13               [--contains [<commit>]] [--no-contains [<commit>]]
14               [--points-at <object>] [--format=<format>]
15               [(-r | --remotes) | (-a | --all)]
16               [--list] [<pattern>...]
17       git branch [--track | --no-track] [-f] <branchname> [<start-point>]
18       git branch (--set-upstream-to=<upstream> | -u <upstream>) [<branchname>]
19       git branch --unset-upstream [<branchname>]
20       git branch (-m | -M) [<oldbranch>] <newbranch>
21       git branch (-c | -C) [<oldbranch>] <newbranch>
22       git branch (-d | -D) [-r] <branchname>...
23       git branch --edit-description [<branchname>]
24

DESCRIPTION

26       If --list is given, or if there are no non-option arguments, existing
27       branches are listed; the current branch will be highlighted in green
28       and marked with an asterisk. Any branches checked out in linked
29       worktrees will be highlighted in cyan and marked with a plus sign.
30       Option -r causes the remote-tracking branches to be listed, and option
31       -a shows both local and remote branches.
32
33       If a <pattern> is given, it is used as a shell wildcard to restrict the
34       output to matching branches. If multiple patterns are given, a branch
35       is shown if it matches any of the patterns.
36
37       Note that when providing a <pattern>, you must use --list; otherwise
38       the command may be interpreted as branch creation.
39
40       With --contains, shows only the branches that contain the named commit
41       (in other words, the branches whose tip commits are descendants of the
42       named commit), --no-contains inverts it. With --merged, only branches
43       merged into the named commit (i.e. the branches whose tip commits are
44       reachable from the named commit) will be listed. With --no-merged only
45       branches not merged into the named commit will be listed. If the
46       <commit> argument is missing it defaults to HEAD (i.e. the tip of the
47       current branch).
48
49       The command’s second form creates a new branch head named <branchname>
50       which points to the current HEAD, or <start-point> if given. As a
51       special case, for <start-point>, you may use "A...B" as a shortcut for
52       the merge base of A and B if there is exactly one merge base. You can
53       leave out at most one of A and B, in which case it defaults to HEAD.
54
55       Note that this will create the new branch, but it will not switch the
56       working tree to it; use "git switch <newbranch>" to switch to the new
57       branch.
58
59       When a local branch is started off a remote-tracking branch, Git sets
60       up the branch (specifically the branch.<name>.remote and
61       branch.<name>.merge configuration entries) so that git pull will
62       appropriately merge from the remote-tracking branch. This behavior may
63       be changed via the global branch.autoSetupMerge configuration flag.
64       That setting can be overridden by using the --track and --no-track
65       options, and changed later using git branch --set-upstream-to.
66
67       With a -m or -M option, <oldbranch> will be renamed to <newbranch>. If
68       <oldbranch> had a corresponding reflog, it is renamed to match
69       <newbranch>, and a reflog entry is created to remember the branch
70       renaming. If <newbranch> exists, -M must be used to force the rename to
71       happen.
72
73       The -c and -C options have the exact same semantics as -m and -M,
74       except instead of the branch being renamed, it will be copied to a new
75       name, along with its config and reflog.
76
77       With a -d or -D option, <branchname> will be deleted. You may specify
78       more than one branch for deletion. If the branch currently has a reflog
79       then the reflog will also be deleted.
80
81       Use -r together with -d to delete remote-tracking branches. Note, that
82       it only makes sense to delete remote-tracking branches if they no
83       longer exist in the remote repository or if git fetch was configured
84       not to fetch them again. See also the prune subcommand of git-remote(1)
85       for a way to clean up all obsolete remote-tracking branches.
86

OPTIONS

88       -d, --delete
89           Delete a branch. The branch must be fully merged in its upstream
90           branch, or in HEAD if no upstream was set with --track or
91           --set-upstream-to.
92
93       -D
94           Shortcut for --delete --force.
95
96       --create-reflog
97           Create the branch’s reflog. This activates recording of all changes
98           made to the branch ref, enabling use of date based sha1 expressions
99           such as "<branchname>@{yesterday}". Note that in non-bare
100           repositories, reflogs are usually enabled by default by the
101           core.logAllRefUpdates config option. The negated form
102           --no-create-reflog only overrides an earlier --create-reflog, but
103           currently does not negate the setting of core.logAllRefUpdates.
104
105       -f, --force
106           Reset <branchname> to <startpoint>, even if <branchname> exists
107           already. Without -f, git branch refuses to change an existing
108           branch. In combination with -d (or --delete), allow deleting the
109           branch irrespective of its merged status, or whether it even points
110           to a valid commit. In combination with -m (or --move), allow
111           renaming the branch even if the new branch name already exists, the
112           same applies for -c (or --copy).
113
114       -m, --move
115           Move/rename a branch and the corresponding reflog.
116
117       -M
118           Shortcut for --move --force.
119
120       -c, --copy
121           Copy a branch and the corresponding reflog.
122
123       -C
124           Shortcut for --copy --force.
125
126       --color[=<when>]
127           Color branches to highlight current, local, and remote-tracking
128           branches. The value must be always (the default), never, or auto.
129
130       --no-color
131           Turn off branch colors, even when the configuration file gives the
132           default to color output. Same as --color=never.
133
134       -i, --ignore-case
135           Sorting and filtering branches are case insensitive.
136
137       --column[=<options>], --no-column
138           Display branch listing in columns. See configuration variable
139           column.branch for option syntax.  --column and --no-column without
140           options are equivalent to always and never respectively.
141
142           This option is only applicable in non-verbose mode.
143
144       -r, --remotes
145           List or delete (if used with -d) the remote-tracking branches.
146           Combine with --list to match the optional pattern(s).
147
148       -a, --all
149           List both remote-tracking branches and local branches. Combine with
150           --list to match optional pattern(s).
151
152       -l, --list
153           List branches. With optional <pattern>..., e.g.  git branch --list
154           'maint-*', list only the branches that match the pattern(s).
155
156       --show-current
157           Print the name of the current branch. In detached HEAD state,
158           nothing is printed.
159
160       -v, -vv, --verbose
161           When in list mode, show sha1 and commit subject line for each head,
162           along with relationship to upstream branch (if any). If given
163           twice, print the path of the linked worktree (if any) and the name
164           of the upstream branch, as well (see also git remote show
165           <remote>). Note that the current worktree’s HEAD will not have its
166           path printed (it will always be your current directory).
167
168       -q, --quiet
169           Be more quiet when creating or deleting a branch, suppressing
170           non-error messages.
171
172       --abbrev=<n>
173           In the verbose listing that show the commit object name, show the
174           shortest prefix that is at least <n> hexdigits long that uniquely
175           refers the object. The default value is 7 and can be overridden by
176           the core.abbrev config option.
177
178       --no-abbrev
179           Display the full sha1s in the output listing rather than
180           abbreviating them.
181
182       -t, --track
183           When creating a new branch, set up branch.<name>.remote and
184           branch.<name>.merge configuration entries to mark the start-point
185           branch as "upstream" from the new branch. This configuration will
186           tell git to show the relationship between the two branches in git
187           status and git branch -v. Furthermore, it directs git pull without
188           arguments to pull from the upstream when the new branch is checked
189           out.
190
191           This behavior is the default when the start point is a
192           remote-tracking branch. Set the branch.autoSetupMerge configuration
193           variable to false if you want git switch, git checkout and git
194           branch to always behave as if --no-track were given. Set it to
195           always if you want this behavior when the start-point is either a
196           local or remote-tracking branch.
197
198       --no-track
199           Do not set up "upstream" configuration, even if the
200           branch.autoSetupMerge configuration variable is true.
201
202       --set-upstream
203           As this option had confusing syntax, it is no longer supported.
204           Please use --track or --set-upstream-to instead.
205
206       -u <upstream>, --set-upstream-to=<upstream>
207           Set up <branchname>'s tracking information so <upstream> is
208           considered <branchname>'s upstream branch. If no <branchname> is
209           specified, then it defaults to the current branch.
210
211       --unset-upstream
212           Remove the upstream information for <branchname>. If no branch is
213           specified it defaults to the current branch.
214
215       --edit-description
216           Open an editor and edit the text to explain what the branch is for,
217           to be used by various other commands (e.g.  format-patch,
218           request-pull, and merge (if enabled)). Multi-line explanations may
219           be used.
220
221       --contains [<commit>]
222           Only list branches which contain the specified commit (HEAD if not
223           specified). Implies --list.
224
225       --no-contains [<commit>]
226           Only list branches which don’t contain the specified commit (HEAD
227           if not specified). Implies --list.
228
229       --merged [<commit>]
230           Only list branches whose tips are reachable from the specified
231           commit (HEAD if not specified). Implies --list.
232
233       --no-merged [<commit>]
234           Only list branches whose tips are not reachable from the specified
235           commit (HEAD if not specified). Implies --list.
236
237       <branchname>
238           The name of the branch to create or delete. The new branch name
239           must pass all checks defined by git-check-ref-format(1). Some of
240           these checks may restrict the characters allowed in a branch name.
241
242       <start-point>
243           The new branch head will point to this commit. It may be given as a
244           branch name, a commit-id, or a tag. If this option is omitted, the
245           current HEAD will be used instead.
246
247       <oldbranch>
248           The name of an existing branch to rename.
249
250       <newbranch>
251           The new name for an existing branch. The same restrictions as for
252           <branchname> apply.
253
254       --sort=<key>
255           Sort based on the key given. Prefix - to sort in descending order
256           of the value. You may use the --sort=<key> option multiple times,
257           in which case the last key becomes the primary key. The keys
258           supported are the same as those in git for-each-ref. Sort order
259           defaults to the value configured for the branch.sort variable if
260           exists, or to sorting based on the full refname (including refs/...
261           prefix). This lists detached HEAD (if present) first, then local
262           branches and finally remote-tracking branches. See git-config(1).
263
264       --points-at <object>
265           Only list branches of the given object.
266
267       --format <format>
268           A string that interpolates %(fieldname) from a branch ref being
269           shown and the object it points at. The format is the same as that
270           of git-for-each-ref(1).
271

CONFIGURATION

273       pager.branch is only respected when listing branches, i.e., when --list
274       is used or implied. The default is to use a pager. See git-config(1).
275

EXAMPLES

277       Start development from a known tag
278
279               $ git clone git://git.kernel.org/pub/scm/.../linux-2.6 my2.6
280               $ cd my2.6
281               $ git branch my2.6.14 v2.6.14   (1)
282               $ git switch my2.6.14
283
284            1. This step and the next one could be combined into a single
285               step with "checkout -b my2.6.14 v2.6.14".
286
287       Delete an unneeded branch
288
289               $ git clone git://git.kernel.org/.../git.git my.git
290               $ cd my.git
291               $ git branch -d -r origin/todo origin/html origin/man   (1)
292               $ git branch -D test                                    (2)
293
294            1. Delete the remote-tracking branches "todo", "html" and
295               "man". The next fetch or pull will create them again
296               unless you configure them not to. See git-fetch(1).
297            2. Delete the "test" branch even if the "master" branch (or
298               whichever branch is currently checked out) does not have
299               all commits from the test branch.
300
301       Listing branches from a specific remote
302
303               $ git branch -r -l '<remote>/<pattern>'                 (1)
304               $ git for-each-ref 'refs/remotes/<remote>/<pattern>'    (2)
305
306            1. Using -a would conflate <remote> with any local branches
307               you happen to have been prefixed with the same <remote>
308               pattern.
309            2. for-each-ref can take a wide range of options. See git-
310               for-each-ref(1)
311
312       Patterns will normally need quoting.
313

NOTES

315       If you are creating a branch that you want to switch to immediately, it
316       is easier to use the "git switch" command with its -c option to do the
317       same thing with a single command.
318
319       The options --contains, --no-contains, --merged and --no-merged serve
320       four related but different purposes:
321
322--contains <commit> is used to find all branches which will need
323           special attention if <commit> were to be rebased or amended, since
324           those branches contain the specified <commit>.
325
326--no-contains <commit> is the inverse of that, i.e. branches that
327           don’t contain the specified <commit>.
328
329--merged is used to find all branches which can be safely deleted,
330           since those branches are fully contained by HEAD.
331
332--no-merged is used to find branches which are candidates for
333           merging into HEAD, since those branches are not fully contained by
334           HEAD.
335
336       When combining multiple --contains and --no-contains filters, only
337       references that contain at least one of the --contains commits and
338       contain none of the --no-contains commits are shown.
339
340       When combining multiple --merged and --no-merged filters, only
341       references that are reachable from at least one of the --merged commits
342       and from none of the --no-merged commits are shown.
343

SEE ALSO

345       git-check-ref-format(1), git-fetch(1), git-remote(1), “Understanding
346       history: What is a branch?”[1] in the Git User’s Manual.
347

GIT

349       Part of the git(1) suite
350

NOTES

352        1. “Understanding history: What is a branch?”
353           file:///usr/share/doc/git/user-manual.html#what-is-a-branch
354
355
356
357Git 2.33.1                        2021-10-12                     GIT-BRANCH(1)
Impressum