git-new-branch(1)

# git-new-branch(1) Manual Page

## NAME

git-new-branch - Create and switch to a new branch with correct tracking information.

## SYNOPSIS

    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>
    git new-branch --inject_current <branch_name>

## DESCRIPTION

Creates a new branch. By default the new branch will track the configured upstream for the repo (defaults to origin/main). 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.

--upstream <REF>

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

--lkgr

  Alias for `--upstream lkgr`.

--inject_current

  Set the tracking (upstream) branch of the newly-created branch to the tracking (upstream) branch of the currently-checked-out branch and set the tracking (upstream) branch of the currently-checked-out branch to the newly-created branch.

      Before: current > upstream
      After: current > new > upstream

<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's default branch or origin/main if that can’t be found. This is considered to be the root branch.

## EXAMPLE

    $ git map-branches -v
    origin/main
      cool_feature         [ 4 commits            ]
        subfeature         [ 2 commits | behind 1 ]
      fixit                [ 2 commits            ]
        frozen_branch *    [ 3 commits            ]

    $ git new-branch independent_cl

    $ git map-branches -v
    origin/main
      cool_feature        [ 4 commits            ]
        subfeature        [ 2 commits | behind 1 ]
      fixit               [ 2 commits            ]
        frozen_branch     [ 3 commits            ]
      independent_cl *

    $ vi foo && git add -A && git commit -m foo
    $ git map-branches -v
    origin/main
      cool_feature        [ 4 commits            ]
        subfeature        [ 2 commits | behind 1 ]
      fixit               [ 2 commits            ]
        frozen_branch     [ 3 commits            ]
      independent_cl *    [ 1 commit             ]

    $ git new-branch --upstream subfeature nested_cl

    $ git map-branches -v
    origin/main
      cool_feature       [ 4 commits            ]
        subfeature       [ 2 commits | behind 1 ] <1>
          nested_cl *
      fixit              [ 2 commits            ]
        frozen_branch    [ 3 commits            ]
      independent_cl     [ 1 commit             ]

    $ git checkout cool_feature
    Switched to branch 'cool_feature'
    Your branch is ahead of 'origin/main' by 4 commits.
      (use "git push" to publish your local commits)

    $ git new-branch --upstream_current cl_depends_on_cool_feature

    $ git map-branches -v
    origin/main
      cool_feature                      [ 4 commits            ]
        cl_depends_on_cool_feature *
        subfeature                      [ 2 commits | behind 1 ]
          nested_cl
      fixit                             [ 2 commits            ]
        frozen_branch                   [ 3 commits            ]
      independent_cl                    [ 1 commit             ]

    $ git checkout subfeature
    Your branch and 'cool_feature' have diverged,
    and have 2 and 1 different commits each, respectively.
      (use "git pull" if you want to integrate the remote branch with yours)

    $ git new-branch --inject_current injected_cl

    $ git map-branches -v
    origin/main
      cool_feature                    [ 4 commits            ]
        cl_depends_on_cool_feature
        injected_cl *
          subfeature                  [ 2 commits | behind 1 ]
            nested_cl
      fixit                           [ 2 commits            ]
        frozen_branch                 [ 3 commits            ]
      independent_cl                  [ 1 commit             ]

1. Note that these branches are cyan because they are currently the same commit object. See git-map-branches(1) for more detail.

## SUGGESTED ALIASES

Some common short-hand aliases. Feel free to add these to your ~/.gitconfig file.

    [alias]
      nb = new-branch
      tb = new-branch --upstream_current  <1>

1. mnemonic: tb → "track branch"

## SEE ALSO

git-rebase-update(1), git-reparent-branch(1), git-rename-branch(1), git-upstream-diff(1)

## CHROMIUM DEPOT_TOOLS

Part of the chromium depot_tools(7) suite. These tools are meant to assist with the development of chromium and related projects. Download the tools by checking out the git repository.