<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<article lang="en" id="git-branch(1)">
<articleinfo>
    <title>git-branch(1)</title>
        <indexterm>
                <primary>git-branch(1)</primary>
        </indexterm>
</articleinfo>
<simplesect id="_name">
<title>NAME</title>
<simpara>git-branch - List, create, or delete branches</simpara>
</simplesect>
<simplesect id="_synopsis">
<title>SYNOPSIS</title>
<blockquote>
<literallayout><emphasis>git branch</emphasis> [--color | --no-color] [-r | -a]
        [-v [--abbrev=&lt;length&gt; | --no-abbrev]]
        [(--merged | --no-merged | --contains) [&lt;commit&gt;]]
<emphasis>git branch</emphasis> [--track | --no-track] [-l] [-f] &lt;branchname&gt; [&lt;start-point&gt;]
<emphasis>git branch</emphasis> (-m | -M) [&lt;oldbranch&gt;] &lt;newbranch&gt;
<emphasis>git branch</emphasis> (-d | -D) [-r] &lt;branchname&gt;&#8230;</literallayout>
</blockquote>
</simplesect>
<simplesect id="_description">
<title>DESCRIPTION</title>
<simpara>With no arguments, existing branches are listed, the current branch will
be highlighted with an asterisk.  Option <literal>-r</literal> causes the remote-tracking
branches to be listed, and option <literal>-a</literal> shows both.</simpara>
<simpara>With <literal>--contains</literal>, shows only the branches that contains the named commit
(in other words, the branches whose tip commits are descendant of the
named commit).  With <literal>--merged</literal>, only branches merged into the named
commit (i.e. the branches whose tip commits are reachable from the named
commit) will be listed.  With <literal>--no-merged</literal> only branches not merged into
the named commit will be listed.  Missing &lt;commit&gt; argument defaults to
<emphasis>HEAD</emphasis> (i.e. the tip of the current branch).</simpara>
<simpara>In its second form, a new branch named &lt;branchname&gt; will be created.
It will start out with a head equal to the one given as &lt;start-point&gt;.
If no &lt;start-point&gt; is given, the branch will be created with a head
equal to that of the currently checked out branch.</simpara>
<simpara>Note that this will create the new branch, but it will not switch the
working tree to it; use "git checkout &lt;newbranch&gt;" to switch to the
new branch.</simpara>
<simpara>When a local branch is started off a remote branch, git sets up the
branch so that <emphasis>git-pull</emphasis> will appropriately merge from
the remote branch. This behavior may be changed via the global
<literal>branch.autosetupmerge</literal> configuration flag. That setting can be
overridden by using the <literal>--track</literal> and <literal>--no-track</literal> options.</simpara>
<simpara>With a <emphasis>-m</emphasis> or <emphasis>-M</emphasis> option, &lt;oldbranch&gt; will be renamed to &lt;newbranch&gt;.
If &lt;oldbranch&gt; had a corresponding reflog, it is renamed to match
&lt;newbranch&gt;, and a reflog entry is created to remember the branch
renaming. If &lt;newbranch&gt; exists, -M must be used to force the rename
to happen.</simpara>
<simpara>With a <literal>-d</literal> or <literal>-D</literal> option, <literal>&lt;branchname&gt;</literal> will be deleted.  You may
specify more than one branch for deletion.  If the branch currently
has a reflog then the reflog will also be deleted.</simpara>
<simpara>Use -r together with -d to delete remote-tracking branches. Note, that it
only makes sense to delete remote-tracking branches if they no longer exist
in remote repository or if <emphasis>git-fetch</emphasis> was configured not to fetch
them again. See also <emphasis>prune</emphasis> subcommand of <xref linkend="git-remote(1)"/> for way to
clean up all obsolete remote-tracking branches.</simpara>
</simplesect>
<simplesect id="_options">
<title>OPTIONS</title>
<variablelist>
<varlistentry>
<term>
-d
</term>
<listitem>
<simpara>
        Delete a branch. The branch must be fully merged in HEAD.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-D
</term>
<listitem>
<simpara>
        Delete a branch irrespective of its merged status.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-l
</term>
<listitem>
<simpara>
        Create the branch&#8217;s reflog.  This activates recording of
        all changes made to the branch ref, enabling use of date
        based sha1 expressions such as "&lt;branchname&gt;@{yesterday}".
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-f
</term>
<listitem>
<simpara>
        Force the creation of a new branch even if it means deleting
        a branch that already exists with the same name.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-m
</term>
<listitem>
<simpara>
        Move/rename a branch and the corresponding reflog.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-M
</term>
<listitem>
<simpara>
        Move/rename a branch even if the new branchname already exists.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--color
</term>
<listitem>
<simpara>
        Color branches to highlight current, local, and remote branches.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--no-color
</term>
<listitem>
<simpara>
        Turn off branch colors, even when the configuration file gives the
        default to color output.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-r
</term>
<listitem>
<simpara>
        List or delete (if used with -d) the remote-tracking branches.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-a
</term>
<listitem>
<simpara>
        List both remote-tracking branches and local branches.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
-v
</term>
<term>
--verbose
</term>
<listitem>
<simpara>
        Show sha1 and commit subject line for each head.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--abbrev=&lt;length&gt;
</term>
<listitem>
<simpara>
        Alter minimum display length for sha1 in output listing,
        default value is 7.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--no-abbrev
</term>
<listitem>
<simpara>
        Display the full sha1s in output listing rather than abbreviating them.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--track
</term>
<listitem>
<simpara>
        When creating a new branch, set up configuration so that <emphasis>git-pull</emphasis>
        will automatically retrieve data from the start point, which must be
        a branch. Use this if you always pull from the same upstream branch
        into the new branch, and if you don&#8217;t want to use "git pull
        &lt;repository&gt; &lt;refspec&gt;" explicitly. This behavior is the default
        when the start point is a remote branch. Set the
        branch.autosetupmerge configuration variable to <literal>false</literal> if you want
        <emphasis>git-checkout</emphasis> and <emphasis>git-branch</emphasis> to always behave as if <emphasis>--no-track</emphasis> were
        given. Set it to <literal>always</literal> if you want this behavior when the
        start-point is either a local or remote branch.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--no-track
</term>
<listitem>
<simpara>
        Ignore the branch.autosetupmerge configuration variable.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--contains &lt;commit&gt;
</term>
<listitem>
<simpara>
        Only list branches which contain the specified commit.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--merged
</term>
<listitem>
<simpara>
        Only list branches which are fully contained by HEAD.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
--no-merged
</term>
<listitem>
<simpara>
        Do not list branches which are fully contained by HEAD.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
&lt;branchname&gt;
</term>
<listitem>
<simpara>
        The name of the branch to create or delete.
        The new branch name must pass all checks defined by
        <xref linkend="git-check-ref-format(1)"/>.  Some of these checks
        may restrict the characters allowed in a branch name.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
&lt;start-point&gt;
</term>
<listitem>
<simpara>
        The new branch will be created with a HEAD equal to this.  It may
        be given as a branch name, a commit-id, or a tag.  If this option
        is omitted, the current branch is assumed.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
&lt;oldbranch&gt;
</term>
<listitem>
<simpara>
        The name of an existing branch to rename.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
&lt;newbranch&gt;
</term>
<listitem>
<simpara>
        The new name for an existing branch. The same restrictions as for
        &lt;branchname&gt; applies.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</simplesect>
<simplesect id="_examples">
<title>Examples</title>
<variablelist>
<varlistentry>
<term>
Start development off of a known tag
</term>
<listitem>
<literallayout>$ git clone git://git.kernel.org/pub/scm/.../linux-2.6 my2.6
$ cd my2.6
$ git branch my2.6.14 v2.6.14   <co id="CO1-1"/>
$ git checkout my2.6.14</literallayout>
<calloutlist>
<callout arearefs="CO1-1">
<simpara>
This step and the next one could be combined into a single step with
"checkout -b my2.6.14 v2.6.14".
</simpara>
</callout>
</calloutlist>
</listitem>
</varlistentry>
<varlistentry>
<term>
Delete unneeded branch
</term>
<listitem>
<literallayout>$ git clone git://git.kernel.org/.../git.git my.git
$ cd my.git
$ git branch -d -r origin/todo origin/html origin/man   <co id="CO2-1"/>
$ git branch -D test                                    <co id="CO2-2"/></literallayout>
<calloutlist>
<callout arearefs="CO2-1">
<simpara>
Delete remote-tracking branches "todo", "html", "man". Next <emphasis>fetch</emphasis> or
<emphasis>pull</emphasis> will create them again unless you configure them not to. See
<xref linkend="git-fetch(1)"/>.
</simpara>
</callout>
<callout arearefs="CO2-2">
<simpara>
Delete "test" branch even if the "master" branch (or whichever branch is
currently checked out) does not have all commits from test branch.
</simpara>
</callout>
</calloutlist>
</listitem>
</varlistentry>
</variablelist>
</simplesect>
<simplesect id="_notes">
<title>Notes</title>
<simpara>If you are creating a branch that you want to immediately checkout, it&#8217;s
easier to use the git checkout command with its <literal>-b</literal> option to create
a branch and check it out with a single command.</simpara>
<simpara>The options <literal>--contains</literal>, <literal>--merged</literal> and <literal>--no-merged</literal> serves three related
but different purposes:</simpara>
<itemizedlist>
<listitem>
<simpara>
<literal>--contains &lt;commit&gt;</literal> is used to find all branches which will need
  special attention if &lt;commit&gt; were to be rebased or amended, since those
  branches contain the specified &lt;commit&gt;.
</simpara>
</listitem>
<listitem>
<simpara>
<literal>--merged</literal> is used to find all branches which can be safely deleted,
  since those branches are fully contained by HEAD.
</simpara>
</listitem>
<listitem>
<simpara>
<literal>--no-merged</literal> is used to find branches which are candidates for merging
  into HEAD, since those branches are not fully contained by HEAD.
</simpara>
</listitem>
</itemizedlist>
</simplesect>
<simplesect id="_author">
<title>Author</title>
<simpara>Written by Linus Torvalds &lt;<ulink url="mailto:torvalds@osdl.org">torvalds@osdl.org</ulink>&gt; and Junio C Hamano &lt;<ulink url="mailto:gitster@pobox.com">gitster@pobox.com</ulink>&gt;</simpara>
</simplesect>
<simplesect id="_documentation">
<title>Documentation</title>
<simpara>Documentation by Junio C Hamano and the git-list &lt;<ulink url="mailto:git@vger.kernel.org">git@vger.kernel.org</ulink>&gt;.</simpara>
</simplesect>
<simplesect id="_git">
<title>GIT</title>
<simpara>Part of the <xref linkend="git(1)"/> suite</simpara>
</simplesect>
</article>
