git-new-branch(1)
=================

NAME
----
git-new-branch -
include::_git-new-branch_desc.helper.txt[]

SYNOPSIS
--------
[verse]
'git new-branch' <branch_name>
'git new-branch' --upstream_current <branch_name>
'git new-branch' --upstream <REF> <branch_name>
'git new-branch' --lkgr <branch_name>

DESCRIPTION
-----------

Creates a new branch. By default the new branch will track the configured
upstream for the repo (defaults to 'origin/master'). If one of the other options
is specified, it will track that other ref instead.

Conceptually, each branch in your repo represents one 'Change List (CL)'. If you
have many independent CLs (i.e. the changes in one do not interact with/depend
on the changes in another), then you should create them as new branches tracking
the default upstream (i.e. `git new-branch <branch_name>`). If you have features
which depend on each other, you should create stacked branches using `git
new-branch --upstream_current <branch_name>`.

OPTIONS
-------

--upstream_current::
  Set the tracking (upstream) branch to the currently-checked-out branch.

--uptstream <REF>::
  Set the tracking (upstream) branch to <REF>. <REF> may be a local branch,
  remote branch, or a tag.

--lkgr::
  Alias for `--upstream lkgr`.

<branch_name>::
  The name for the new branch.


CONFIGURATION VARIABLES
-----------------------

depot-tools.upstream
~~~~~~~~~~~~~~~~~~~~

This configures the default 'upstream' for all new branches. If it is unset, it
defaults to 'origin/master'.  This is considered to be the 'root' branch.

EXAMPLE
-------

[subs="specialcharacters,quotes,attributes,callouts"]
----
[white]**$ git map-branches**
[red]#origin/master#
  [green]#cool_feature#
    [green]#subfeature#
  [aqua]#frozen_changes *#
[white]**$ git new-branch independent_cl**
[white]**$ git map-branches**
[red]#origin/master#
  [green]#cool_feature#
    [green]#subfeature#
  [green]#frozen_changes#
  [aqua]#independent_cl *#
[white]**$ git new-branch --upstream subfeature nested_cl**
[white]**$ git map-branches**
[red]#origin/master#
  [green]#cool_feature#
    [aqua]#subfeature#  <1>
      [aqua]#nested_cl *#
  [green]#frozen_changes#
  [green]#independent_cl#
[white]**$ git checkout cool_feature**
[white]**$ git new-branch --upstream_current cl_depends_on_cool_feature**
[white]**$ git map-branches**
[red]#origin/master#
  [aqua]#cool_feature#
    [aqua]#cl_depends_on_cool_feature *#
    [green]#subfeature#
      [green]#nested_cl#
  [green]#frozen_changes#
  [green]#independent_cl#
----
<1> Note that both branches are cyan because they are currently the same
'commit' object. See linkgit::git-map-branches[1] for more detail.

include::_aliases.txt[]

----
[alias]
  git nb = new-branch
  git tb = new-branch --upstream_current  <1>
----
<1> mnemonic: tb -> "track branch"


SEE ALSO
--------
linkgit:git-rebase-update[1], linkgit:git-reparent-branch[1],
linkgit:git-rename-branch[1], linkgit:git-upstream-diff[1]

include::_footer.txt[]

// vim: ft=asciidoc: