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=<length> | --no-abbrev]]
11               [--column[=<options>] | --no-column] [--sort=<key>]
12               [(--merged | --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 along with its config and
75       reflog will be copied to a new name.
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=<length>
172           Alter the sha1’s minimum display length in the output listing. The
173           default value is 7 and can be overridden by the core.abbrev config
174           option.
175
176       --no-abbrev
177           Display the full sha1s in the output listing rather than
178           abbreviating them.
179
180       -t, --track
181           When creating a new branch, set up branch.<name>.remote and
182           branch.<name>.merge configuration entries to mark the start-point
183           branch as "upstream" from the new branch. This configuration will
184           tell git to show the relationship between the two branches in git
185           status and git branch -v. Furthermore, it directs git pull without
186           arguments to pull from the upstream when the new branch is checked
187           out.
188
189           This behavior is the default when the start point is a
190           remote-tracking branch. Set the branch.autoSetupMerge configuration
191           variable to false if you want git switch, git checkout and git
192           branch to always behave as if --no-track were given. Set it to
193           always if you want this behavior when the start-point is either a
194           local or remote-tracking branch.
195
196       --no-track
197           Do not set up "upstream" configuration, even if the
198           branch.autoSetupMerge configuration variable is true.
199
200       --set-upstream
201           As this option had confusing syntax, it is no longer supported.
202           Please use --track or --set-upstream-to instead.
203
204       -u <upstream>, --set-upstream-to=<upstream>
205           Set up <branchname>'s tracking information so <upstream> is
206           considered <branchname>'s upstream branch. If no <branchname> is
207           specified, then it defaults to the current branch.
208
209       --unset-upstream
210           Remove the upstream information for <branchname>. If no branch is
211           specified it defaults to the current branch.
212
213       --edit-description
214           Open an editor and edit the text to explain what the branch is for,
215           to be used by various other commands (e.g.  format-patch,
216           request-pull, and merge (if enabled)). Multi-line explanations may
217           be used.
218
219       --contains [<commit>]
220           Only list branches which contain the specified commit (HEAD if not
221           specified). Implies --list.
222
223       --no-contains [<commit>]
224           Only list branches which don’t contain the specified commit (HEAD
225           if not specified). Implies --list.
226
227       --merged [<commit>]
228           Only list branches whose tips are reachable from the specified
229           commit (HEAD if not specified). Implies --list, incompatible with
230           --no-merged.
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, incompatible with
235           --merged.
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

SEE ALSO

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

GIT

341       Part of the git(1) suite
342

NOTES

344        1. “Understanding history: What is a branch?”
345           file:///usr/share/doc/git/user-manual.html#what-is-a-branch
346
347
348
349Git 2.26.2                        2020-04-20                     GIT-BRANCH(1)
Impressum