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

CONFIGURATION

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

EXAMPLES

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

NOTES

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

SEE ALSO

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

GIT

348       Part of the git(1) suite
349

NOTES

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