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] [-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       --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       -l, --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       -v, -vv, --verbose
146           When in list mode, show sha1 and commit subject line for each head,
147           along with relationship to upstream branch (if any). If given
148           twice, print the name of the upstream branch, as well (see also git
149           remote show <remote>).
150
151       -q, --quiet
152           Be more quiet when creating or deleting a branch, suppressing
153           non-error messages.
154
155       --abbrev=<length>
156           Alter the sha1’s minimum display length in the output listing. The
157           default value is 7 and can be overridden by the core.abbrev config
158           option.
159
160       --no-abbrev
161           Display the full sha1s in the output listing rather than
162           abbreviating them.
163
164       -t, --track
165           When creating a new branch, set up branch.<name>.remote and
166           branch.<name>.merge configuration entries to mark the start-point
167           branch as "upstream" from the new branch. This configuration will
168           tell git to show the relationship between the two branches in git
169           status and git branch -v. Furthermore, it directs git pull without
170           arguments to pull from the upstream when the new branch is checked
171           out.
172
173           This behavior is the default when the start point is a
174           remote-tracking branch. Set the branch.autoSetupMerge configuration
175           variable to false if you want git checkout and git branch to always
176           behave as if --no-track were given. Set it to always if you want
177           this behavior when the start-point is either a local or
178           remote-tracking branch.
179
180       --no-track
181           Do not set up "upstream" configuration, even if the
182           branch.autoSetupMerge configuration variable is true.
183
184       --set-upstream
185           As this option had confusing syntax, it is no longer supported.
186           Please use --track or --set-upstream-to instead.
187
188       -u <upstream>, --set-upstream-to=<upstream>
189           Set up <branchname>'s tracking information so <upstream> is
190           considered <branchname>'s upstream branch. If no <branchname> is
191           specified, then it defaults to the current branch.
192
193       --unset-upstream
194           Remove the upstream information for <branchname>. If no branch is
195           specified it defaults to the current branch.
196
197       --edit-description
198           Open an editor and edit the text to explain what the branch is for,
199           to be used by various other commands (e.g.  format-patch,
200           request-pull, and merge (if enabled)). Multi-line explanations may
201           be used.
202
203       --contains [<commit>]
204           Only list branches which contain the specified commit (HEAD if not
205           specified). Implies --list.
206
207       --no-contains [<commit>]
208           Only list branches which don’t contain the specified commit (HEAD
209           if not specified). Implies --list.
210
211       --merged [<commit>]
212           Only list branches whose tips are reachable from the specified
213           commit (HEAD if not specified). Implies --list, incompatible with
214           --no-merged.
215
216       --no-merged [<commit>]
217           Only list branches whose tips are not reachable from the specified
218           commit (HEAD if not specified). Implies --list, incompatible with
219           --merged.
220
221       <branchname>
222           The name of the branch to create or delete. The new branch name
223           must pass all checks defined by git-check-ref-format(1). Some of
224           these checks may restrict the characters allowed in a branch name.
225
226       <start-point>
227           The new branch head will point to this commit. It may be given as a
228           branch name, a commit-id, or a tag. If this option is omitted, the
229           current HEAD will be used instead.
230
231       <oldbranch>
232           The name of an existing branch to rename.
233
234       <newbranch>
235           The new name for an existing branch. The same restrictions as for
236           <branchname> apply.
237
238       --sort=<key>
239           Sort based on the key given. Prefix - to sort in descending order
240           of the value. You may use the --sort=<key> option multiple times,
241           in which case the last key becomes the primary key. The keys
242           supported are the same as those in git for-each-ref. Sort order
243           defaults to the value configured for the branch.sort variable if
244           exists, or to sorting based on the full refname (including refs/...
245           prefix). This lists detached HEAD (if present) first, then local
246           branches and finally remote-tracking branches. See git-config(1).
247
248       --points-at <object>
249           Only list branches of the given object.
250
251       --format <format>
252           A string that interpolates %(fieldname) from a branch ref being
253           shown and the object it points at. The format is the same as that
254           of git-for-each-ref(1).
255

CONFIGURATION

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

EXAMPLES

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

NOTES

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

SEE ALSO

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

GIT

312       Part of the git(1) suite
313

NOTES

315        1. “Understanding history: What is a branch?”
316           file:///usr/share/doc/git/user-manual.html#what-is-a-branch
317
318
319
320Git 2.21.0                        02/24/2019                     GIT-BRANCH(1)
Impressum