Autogenerated HTML docs for v1.7.5-rc1
[git/jnareb-git.git] / git-branch.html
blob00533e1173c8eac1f5437926a50979281c8308f3
1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
2 "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
4 <head>
5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
6 <meta name="generator" content="AsciiDoc 8.4.5" />
7 <title>git-branch(1)</title>
8 <style type="text/css">
9 /* Debug borders */
10 p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
12 border: 1px solid red;
16 body {
17 margin: 1em 5% 1em 5%;
20 a {
21 color: blue;
22 text-decoration: underline;
24 a:visited {
25 color: fuchsia;
28 em {
29 font-style: italic;
30 color: navy;
33 strong {
34 font-weight: bold;
35 color: #083194;
38 tt {
39 color: navy;
42 h1, h2, h3, h4, h5, h6 {
43 color: #527bbd;
44 font-family: sans-serif;
45 margin-top: 1.2em;
46 margin-bottom: 0.5em;
47 line-height: 1.3;
50 h1, h2, h3 {
51 border-bottom: 2px solid silver;
53 h2 {
54 padding-top: 0.5em;
56 h3 {
57 float: left;
59 h3 + * {
60 clear: left;
63 div.sectionbody {
64 font-family: serif;
65 margin-left: 0;
68 hr {
69 border: 1px solid silver;
72 p {
73 margin-top: 0.5em;
74 margin-bottom: 0.5em;
77 ul, ol, li > p {
78 margin-top: 0;
81 pre {
82 padding: 0;
83 margin: 0;
86 span#author {
87 color: #527bbd;
88 font-family: sans-serif;
89 font-weight: bold;
90 font-size: 1.1em;
92 span#email {
94 span#revnumber, span#revdate, span#revremark {
95 font-family: sans-serif;
98 div#footer {
99 font-family: sans-serif;
100 font-size: small;
101 border-top: 2px solid silver;
102 padding-top: 0.5em;
103 margin-top: 4.0em;
105 div#footer-text {
106 float: left;
107 padding-bottom: 0.5em;
109 div#footer-badges {
110 float: right;
111 padding-bottom: 0.5em;
114 div#preamble {
115 margin-top: 1.5em;
116 margin-bottom: 1.5em;
118 div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
119 div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
120 div.admonitionblock {
121 margin-top: 1.5em;
122 margin-bottom: 1.5em;
124 div.admonitionblock {
125 margin-top: 2.5em;
126 margin-bottom: 2.5em;
129 div.content { /* Block element content. */
130 padding: 0;
133 /* Block element titles. */
134 div.title, caption.title {
135 color: #527bbd;
136 font-family: sans-serif;
137 font-weight: bold;
138 text-align: left;
139 margin-top: 1.0em;
140 margin-bottom: 0.5em;
142 div.title + * {
143 margin-top: 0;
146 td div.title:first-child {
147 margin-top: 0.0em;
149 div.content div.title:first-child {
150 margin-top: 0.0em;
152 div.content + div.title {
153 margin-top: 0.0em;
156 div.sidebarblock > div.content {
157 background: #ffffee;
158 border: 1px solid silver;
159 padding: 0.5em;
162 div.listingblock > div.content {
163 border: 1px solid silver;
164 background: #f4f4f4;
165 padding: 0.5em;
168 div.quoteblock {
169 padding-left: 2.0em;
170 margin-right: 10%;
172 div.quoteblock > div.attribution {
173 padding-top: 0.5em;
174 text-align: right;
177 div.verseblock {
178 padding-left: 2.0em;
179 margin-right: 10%;
181 div.verseblock > div.content {
182 white-space: pre;
184 div.verseblock > div.attribution {
185 padding-top: 0.75em;
186 text-align: left;
188 /* DEPRECATED: Pre version 8.2.7 verse style literal block. */
189 div.verseblock + div.attribution {
190 text-align: left;
193 div.admonitionblock .icon {
194 vertical-align: top;
195 font-size: 1.1em;
196 font-weight: bold;
197 text-decoration: underline;
198 color: #527bbd;
199 padding-right: 0.5em;
201 div.admonitionblock td.content {
202 padding-left: 0.5em;
203 border-left: 2px solid silver;
206 div.exampleblock > div.content {
207 border-left: 2px solid silver;
208 padding: 0.5em;
211 div.imageblock div.content { padding-left: 0; }
212 span.image img { border-style: none; }
213 a.image:visited { color: white; }
215 dl {
216 margin-top: 0.8em;
217 margin-bottom: 0.8em;
219 dt {
220 margin-top: 0.5em;
221 margin-bottom: 0;
222 font-style: normal;
223 color: navy;
225 dd > *:first-child {
226 margin-top: 0.1em;
229 ul, ol {
230 list-style-position: outside;
232 ol.arabic {
233 list-style-type: decimal;
235 ol.loweralpha {
236 list-style-type: lower-alpha;
238 ol.upperalpha {
239 list-style-type: upper-alpha;
241 ol.lowerroman {
242 list-style-type: lower-roman;
244 ol.upperroman {
245 list-style-type: upper-roman;
248 div.compact ul, div.compact ol,
249 div.compact p, div.compact p,
250 div.compact div, div.compact div {
251 margin-top: 0.1em;
252 margin-bottom: 0.1em;
255 div.tableblock > table {
256 border: 3px solid #527bbd;
258 thead {
259 font-family: sans-serif;
260 font-weight: bold;
262 tfoot {
263 font-weight: bold;
265 td > div.verse {
266 white-space: pre;
268 p.table {
269 margin-top: 0;
271 /* Because the table frame attribute is overriden by CSS in most browsers. */
272 div.tableblock > table[frame="void"] {
273 border-style: none;
275 div.tableblock > table[frame="hsides"] {
276 border-left-style: none;
277 border-right-style: none;
279 div.tableblock > table[frame="vsides"] {
280 border-top-style: none;
281 border-bottom-style: none;
285 div.hdlist {
286 margin-top: 0.8em;
287 margin-bottom: 0.8em;
289 div.hdlist tr {
290 padding-bottom: 15px;
292 dt.hdlist1.strong, td.hdlist1.strong {
293 font-weight: bold;
295 td.hdlist1 {
296 vertical-align: top;
297 font-style: normal;
298 padding-right: 0.8em;
299 color: navy;
301 td.hdlist2 {
302 vertical-align: top;
304 div.hdlist.compact tr {
305 margin: 0;
306 padding-bottom: 0;
309 .comment {
310 background: yellow;
313 @media print {
314 div#footer-badges { display: none; }
317 div#toctitle {
318 color: #527bbd;
319 font-family: sans-serif;
320 font-size: 1.1em;
321 font-weight: bold;
322 margin-top: 1.0em;
323 margin-bottom: 0.1em;
326 div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
327 margin-top: 0;
328 margin-bottom: 0;
330 div.toclevel2 {
331 margin-left: 2em;
332 font-size: 0.9em;
334 div.toclevel3 {
335 margin-left: 4em;
336 font-size: 0.9em;
338 div.toclevel4 {
339 margin-left: 6em;
340 font-size: 0.9em;
342 /* Overrides for manpage documents */
343 h1 {
344 padding-top: 0.5em;
345 padding-bottom: 0.5em;
346 border-top: 2px solid silver;
347 border-bottom: 2px solid silver;
349 h2 {
350 border-style: none;
352 div.sectionbody {
353 margin-left: 5%;
356 @media print {
357 div#toc { display: none; }
360 /* Workarounds for IE6's broken and incomplete CSS2. */
362 div.sidebar-content {
363 background: #ffffee;
364 border: 1px solid silver;
365 padding: 0.5em;
367 div.sidebar-title, div.image-title {
368 color: #527bbd;
369 font-family: sans-serif;
370 font-weight: bold;
371 margin-top: 0.0em;
372 margin-bottom: 0.5em;
375 div.listingblock div.content {
376 border: 1px solid silver;
377 background: #f4f4f4;
378 padding: 0.5em;
381 div.quoteblock-attribution {
382 padding-top: 0.5em;
383 text-align: right;
386 div.verseblock-content {
387 white-space: pre;
389 div.verseblock-attribution {
390 padding-top: 0.75em;
391 text-align: left;
394 div.exampleblock-content {
395 border-left: 2px solid silver;
396 padding-left: 0.5em;
399 /* IE6 sets dynamically generated links as visited. */
400 div#toc a:visited { color: blue; }
401 </style>
402 </head>
403 <body>
404 <div id="header">
405 <h1>
406 git-branch(1) Manual Page
407 </h1>
408 <h2>NAME</h2>
409 <div class="sectionbody">
410 <p>git-branch -
411 List, create, or delete branches
412 </p>
413 </div>
414 </div>
415 <h2 id="_synopsis">SYNOPSIS</h2>
416 <div class="sectionbody">
417 <div class="verseblock">
418 <div class="verseblock-content"><em>git branch</em> [--color[=&lt;when&gt;] | --no-color] [-r | -a]
419 [-v [--abbrev=&lt;length&gt; | --no-abbrev]]
420 [(--merged | --no-merged | --contains) [&lt;commit&gt;]]
421 <em>git branch</em> [--set-upstream | --track | --no-track] [-l] [-f] &lt;branchname&gt; [&lt;start-point&gt;]
422 <em>git branch</em> (-m | -M) [&lt;oldbranch&gt;] &lt;newbranch&gt;
423 <em>git branch</em> (-d | -D) [-r] &lt;branchname&gt;&#8230;</div>
424 <div class="verseblock-attribution">
425 </div></div>
426 </div>
427 <h2 id="_description">DESCRIPTION</h2>
428 <div class="sectionbody">
429 <div class="paragraph"><p>With no arguments, existing branches are listed and the current branch will
430 be highlighted with an asterisk. Option <tt>-r</tt> causes the remote-tracking
431 branches to be listed, and option <tt>-a</tt> shows both.</p></div>
432 <div class="paragraph"><p>With <tt>--contains</tt>, shows only the branches that contain the named commit
433 (in other words, the branches whose tip commits are descendants of the
434 named commit). With <tt>--merged</tt>, only branches merged into the named
435 commit (i.e. the branches whose tip commits are reachable from the named
436 commit) will be listed. With <tt>--no-merged</tt> only branches not merged into
437 the named commit will be listed. If the &lt;commit&gt; argument is missing it
438 defaults to <em>HEAD</em> (i.e. the tip of the current branch).</p></div>
439 <div class="paragraph"><p>The command&#8217;s second form creates a new branch head named &lt;branchname&gt;
440 which points to the current <em>HEAD</em>, or &lt;start-point&gt; if given.</p></div>
441 <div class="paragraph"><p>Note that this will create the new branch, but it will not switch the
442 working tree to it; use "git checkout &lt;newbranch&gt;" to switch to the
443 new branch.</p></div>
444 <div class="paragraph"><p>When a local branch is started off a remote-tracking branch, git sets up the
445 branch so that <em>git pull</em> will appropriately merge from
446 the remote-tracking branch. This behavior may be changed via the global
447 <tt>branch.autosetupmerge</tt> configuration flag. That setting can be
448 overridden by using the <tt>--track</tt> and <tt>--no-track</tt> options, and
449 changed later using <tt>git branch --set-upstream</tt>.</p></div>
450 <div class="paragraph"><p>With a <em>-m</em> or <em>-M</em> option, &lt;oldbranch&gt; will be renamed to &lt;newbranch&gt;.
451 If &lt;oldbranch&gt; had a corresponding reflog, it is renamed to match
452 &lt;newbranch&gt;, and a reflog entry is created to remember the branch
453 renaming. If &lt;newbranch&gt; exists, -M must be used to force the rename
454 to happen.</p></div>
455 <div class="paragraph"><p>With a <tt>-d</tt> or <tt>-D</tt> option, <tt>&lt;branchname&gt;</tt> will be deleted. You may
456 specify more than one branch for deletion. If the branch currently
457 has a reflog then the reflog will also be deleted.</p></div>
458 <div class="paragraph"><p>Use -r together with -d to delete remote-tracking branches. Note, that it
459 only makes sense to delete remote-tracking branches if they no longer exist
460 in the remote repository or if <em>git fetch</em> was configured not to fetch
461 them again. See also the <em>prune</em> subcommand of <a href="git-remote.html">git-remote(1)</a> for a
462 way to clean up all obsolete remote-tracking branches.</p></div>
463 </div>
464 <h2 id="_options">OPTIONS</h2>
465 <div class="sectionbody">
466 <div class="dlist"><dl>
467 <dt class="hdlist1">
469 </dt>
470 <dd>
472 Delete a branch. The branch must be fully merged in its
473 upstream branch, or in <tt>HEAD</tt> if no upstream was set with
474 <tt>--track</tt> or <tt>--set-upstream</tt>.
475 </p>
476 </dd>
477 <dt class="hdlist1">
479 </dt>
480 <dd>
482 Delete a branch irrespective of its merged status.
483 </p>
484 </dd>
485 <dt class="hdlist1">
487 </dt>
488 <dd>
490 Create the branch&#8217;s reflog. This activates recording of
491 all changes made to the branch ref, enabling use of date
492 based sha1 expressions such as "&lt;branchname&gt;@{yesterday}".
493 Note that in non-bare repositories, reflogs are usually
494 enabled by default by the <tt>core.logallrefupdates</tt> config option.
495 </p>
496 </dd>
497 <dt class="hdlist1">
499 </dt>
500 <dt class="hdlist1">
501 --force
502 </dt>
503 <dd>
505 Reset &lt;branchname&gt; to &lt;startpoint&gt; if &lt;branchname&gt; exists
506 already. Without <tt>-f</tt> <em>git branch</em> refuses to change an existing branch.
507 </p>
508 </dd>
509 <dt class="hdlist1">
511 </dt>
512 <dd>
514 Move/rename a branch and the corresponding reflog.
515 </p>
516 </dd>
517 <dt class="hdlist1">
519 </dt>
520 <dd>
522 Move/rename a branch even if the new branch name already exists.
523 </p>
524 </dd>
525 <dt class="hdlist1">
526 --color[=&lt;when&gt;]
527 </dt>
528 <dd>
530 Color branches to highlight current, local, and
531 remote-tracking branches.
532 The value must be always (the default), never, or auto.
533 </p>
534 </dd>
535 <dt class="hdlist1">
536 --no-color
537 </dt>
538 <dd>
540 Turn off branch colors, even when the configuration file gives the
541 default to color output.
542 Same as <tt>--color=never</tt>.
543 </p>
544 </dd>
545 <dt class="hdlist1">
547 </dt>
548 <dd>
550 List or delete (if used with -d) the remote-tracking branches.
551 </p>
552 </dd>
553 <dt class="hdlist1">
555 </dt>
556 <dd>
558 List both remote-tracking branches and local branches.
559 </p>
560 </dd>
561 <dt class="hdlist1">
563 </dt>
564 <dt class="hdlist1">
565 --verbose
566 </dt>
567 <dd>
569 Show sha1 and commit subject line for each head, along with
570 relationship to upstream branch (if any). If given twice, print
571 the name of the upstream branch, as well.
572 </p>
573 </dd>
574 <dt class="hdlist1">
575 --abbrev=&lt;length&gt;
576 </dt>
577 <dd>
579 Alter the sha1&#8217;s minimum display length in the output listing.
580 The default value is 7.
581 </p>
582 </dd>
583 <dt class="hdlist1">
584 --no-abbrev
585 </dt>
586 <dd>
588 Display the full sha1s in the output listing rather than abbreviating them.
589 </p>
590 </dd>
591 <dt class="hdlist1">
593 </dt>
594 <dt class="hdlist1">
595 --track
596 </dt>
597 <dd>
599 When creating a new branch, set up configuration to mark the
600 start-point branch as "upstream" from the new branch. This
601 configuration will tell git to show the relationship between the
602 two branches in <tt>git status</tt> and <tt>git branch -v</tt>. Furthermore,
603 it directs <tt>git pull</tt> without arguments to pull from the
604 upstream when the new branch is checked out.
605 </p>
606 <div class="paragraph"><p>This behavior is the default when the start point is a remote-tracking branch.
607 Set the branch.autosetupmerge configuration variable to <tt>false</tt> if you
608 want <tt>git checkout</tt> and <tt>git branch</tt> to always behave as if <em>--no-track</em>
609 were given. Set it to <tt>always</tt> if you want this behavior when the
610 start-point is either a local or remote-tracking branch.</p></div>
611 </dd>
612 <dt class="hdlist1">
613 --no-track
614 </dt>
615 <dd>
617 Do not set up "upstream" configuration, even if the
618 branch.autosetupmerge configuration variable is true.
619 </p>
620 </dd>
621 <dt class="hdlist1">
622 --set-upstream
623 </dt>
624 <dd>
626 If specified branch does not exist yet or if <em>--force</em> has been
627 given, acts exactly like <em>--track</em>. Otherwise sets up configuration
628 like <em>--track</em> would when creating the branch, except that where
629 branch points to is not changed.
630 </p>
631 </dd>
632 <dt class="hdlist1">
633 --contains &lt;commit&gt;
634 </dt>
635 <dd>
637 Only list branches which contain the specified commit.
638 </p>
639 </dd>
640 <dt class="hdlist1">
641 --merged [&lt;commit&gt;]
642 </dt>
643 <dd>
645 Only list branches whose tips are reachable from the
646 specified commit (HEAD if not specified).
647 </p>
648 </dd>
649 <dt class="hdlist1">
650 --no-merged [&lt;commit&gt;]
651 </dt>
652 <dd>
654 Only list branches whose tips are not reachable from the
655 specified commit (HEAD if not specified).
656 </p>
657 </dd>
658 <dt class="hdlist1">
659 &lt;branchname&gt;
660 </dt>
661 <dd>
663 The name of the branch to create or delete.
664 The new branch name must pass all checks defined by
665 <a href="git-check-ref-format.html">git-check-ref-format(1)</a>. Some of these checks
666 may restrict the characters allowed in a branch name.
667 </p>
668 </dd>
669 <dt class="hdlist1">
670 &lt;start-point&gt;
671 </dt>
672 <dd>
674 The new branch head will point to this commit. It may be
675 given as a branch name, a commit-id, or a tag. If this
676 option is omitted, the current HEAD will be used instead.
677 </p>
678 </dd>
679 <dt class="hdlist1">
680 &lt;oldbranch&gt;
681 </dt>
682 <dd>
684 The name of an existing branch to rename.
685 </p>
686 </dd>
687 <dt class="hdlist1">
688 &lt;newbranch&gt;
689 </dt>
690 <dd>
692 The new name for an existing branch. The same restrictions as for
693 &lt;branchname&gt; apply.
694 </p>
695 </dd>
696 </dl></div>
697 </div>
698 <h2 id="_examples">Examples</h2>
699 <div class="sectionbody">
700 <div class="dlist"><dl>
701 <dt class="hdlist1">
702 Start development from a known tag
703 </dt>
704 <dd>
705 <div class="listingblock">
706 <div class="content">
707 <pre><tt>$ git clone git://git.kernel.org/pub/scm/.../linux-2.6 my2.6
708 $ cd my2.6
709 $ git branch my2.6.14 v2.6.14 <b>&lt;1&gt;</b>
710 $ git checkout my2.6.14</tt></pre>
711 </div></div>
712 <div class="colist arabic"><ol>
713 <li>
715 This step and the next one could be combined into a single step with
716 "checkout -b my2.6.14 v2.6.14".
717 </p>
718 </li>
719 </ol></div>
720 </dd>
721 <dt class="hdlist1">
722 Delete an unneeded branch
723 </dt>
724 <dd>
725 <div class="listingblock">
726 <div class="content">
727 <pre><tt>$ git clone git://git.kernel.org/.../git.git my.git
728 $ cd my.git
729 $ git branch -d -r origin/todo origin/html origin/man <b>&lt;1&gt;</b>
730 $ git branch -D test <b>&lt;2&gt;</b></tt></pre>
731 </div></div>
732 <div class="colist arabic"><ol>
733 <li>
735 Delete the remote-tracking branches "todo", "html" and "man". The next
736 <em>fetch</em> or <em>pull</em> will create them again unless you configure them not to.
737 See <a href="git-fetch.html">git-fetch(1)</a>.
738 </p>
739 </li>
740 <li>
742 Delete the "test" branch even if the "master" branch (or whichever branch
743 is currently checked out) does not have all commits from the test branch.
744 </p>
745 </li>
746 </ol></div>
747 </dd>
748 </dl></div>
749 </div>
750 <h2 id="_notes">Notes</h2>
751 <div class="sectionbody">
752 <div class="paragraph"><p>If you are creating a branch that you want to checkout immediately, it is
753 easier to use the git checkout command with its <tt>-b</tt> option to create
754 a branch and check it out with a single command.</p></div>
755 <div class="paragraph"><p>The options <tt>--contains</tt>, <tt>--merged</tt> and <tt>--no-merged</tt> serve three related
756 but different purposes:</p></div>
757 <div class="ulist"><ul>
758 <li>
760 <tt>--contains &lt;commit&gt;</tt> is used to find all branches which will need
761 special attention if &lt;commit&gt; were to be rebased or amended, since those
762 branches contain the specified &lt;commit&gt;.
763 </p>
764 </li>
765 <li>
767 <tt>--merged</tt> is used to find all branches which can be safely deleted,
768 since those branches are fully contained by HEAD.
769 </p>
770 </li>
771 <li>
773 <tt>--no-merged</tt> is used to find branches which are candidates for merging
774 into HEAD, since those branches are not fully contained by HEAD.
775 </p>
776 </li>
777 </ul></div>
778 </div>
779 <h2 id="_see_also">SEE ALSO</h2>
780 <div class="sectionbody">
781 <div class="paragraph"><p><a href="git-check-ref-format.html">git-check-ref-format(1)</a>,
782 <a href="git-fetch.html">git-fetch(1)</a>,
783 <a href="git-remote.html">git-remote(1)</a>,
784 <a href="user-manual.html#what-is-a-branch">&#8220;Understanding history: What is
785 a branch?&#8221;</a> in the Git User&#8217;s Manual.</p></div>
786 </div>
787 <h2 id="_git">GIT</h2>
788 <div class="sectionbody">
789 <div class="paragraph"><p>Part of the <a href="git.html">git(1)</a> suite</p></div>
790 </div>
791 <div id="footer">
792 <div id="footer-text">
793 Last updated 2011-03-15 23:30:13 UTC
794 </div>
795 </div>
796 </body>
797 </html>