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] [-r | -a]
10               [--list] [-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>] [<pattern>...]
15       git branch [--track | --no-track] [-l] [-f] <branchname> [<start-point>]
16       git branch (--set-upstream-to=<upstream> | -u <upstream>) [<branchname>]
17       git branch --unset-upstream [<branchname>]
18       git branch (-m | -M) [<oldbranch>] <newbranch>
19       git branch (-c | -C) [<oldbranch>] <newbranch>
20       git branch (-d | -D) [-r] <branchname>...
21       git branch --edit-description [<branchname>]
22
23

DESCRIPTION

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

OPTIONS

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

CONFIGURATION

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

EXAMPLES

264       Start development from a known tag
265
266               $ git clone git://git.kernel.org/pub/scm/.../linux-2.6 my2.6
267               $ cd my2.6
268               $ git branch my2.6.14 v2.6.14   (1)
269               $ git checkout my2.6.14
270
271           1. This step and the next one could be combined into a single step
272           with "checkout -b my2.6.14 v2.6.14".
273
274       Delete an unneeded branch
275
276               $ git clone git://git.kernel.org/.../git.git my.git
277               $ cd my.git
278               $ git branch -d -r origin/todo origin/html origin/man   (1)
279               $ git branch -D test                                    (2)
280
281           1. Delete the remote-tracking branches "todo", "html" and "man".
282           The next fetch or pull will create them again unless you configure
283           them not to. See git-fetch(1).
284           2. Delete the "test" branch even if the "master" branch (or
285           whichever branch is currently checked out) does not have all
286           commits from the test branch.
287

NOTES

289       If you are creating a branch that you want to checkout immediately, it
290       is easier to use the git checkout command with its -b option to create
291       a branch and check it out with a single command.
292
293       The options --contains, --no-contains, --merged and --no-merged serve
294       four related but different purposes:
295
296       ·   --contains <commit> is used to find all branches which will need
297           special attention if <commit> were to be rebased or amended, since
298           those branches contain the specified <commit>.
299
300       ·   --no-contains <commit> is the inverse of that, i.e. branches that
301           don’t contain the specified <commit>.
302
303       ·   --merged is used to find all branches which can be safely deleted,
304           since those branches are fully contained by HEAD.
305
306       ·   --no-merged is used to find branches which are candidates for
307           merging into HEAD, since those branches are not fully contained by
308           HEAD.
309

SEE ALSO

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

GIT

315       Part of the git(1) suite
316

NOTES

318        1. “Understanding history: What is a branch?”
319           file:///usr/share/doc/git/user-manual.html#what-is-a-branch
320
321
322
323Git 2.18.1                        05/14/2019                     GIT-BRANCH(1)
Impressum