Git branch

Internal

• Git Commands
• Git Concepts

Overview

git branch is used to perform branch-related operations: listing existing branches, creating new local and remote branches, renaming branches and deleting branches.

Use git checkout to check out the content of a branch in the local work area.

For a description of the concepts behind Git branches, see:

Git Concepts - Branches

List Existing Branches

The local (topic) branches in the repository are displayed by executing git branch without any argument, or with the default --list argument:

git branch [--list]

The output of the command reflects the content of the .git/refs/heads/ directory.

The tracking branches are displayed by executing:

git branch -r

The output of the command reflects the content of the .git/refs/remotes/<remote-name> directories.

To display both local and tracking branches, use:

git branch -a

Branch Details

git show-branch

Create a New Local Branch

A new local branch can be created with

git branch <new-branch-name>

This creates a new local topic branch new-branch-name rooted in the HEAD of the current branch, so the default behavior is to create a branch right at the point where you're working right now. An alternate starting commit can be provided by specifying the commit hash.

git branch <new-branch-name> [starting-commit]

Immediately after creation, the branch exists just as a name in the local repository. It does not change the working directory to use the new branch. From an implementation point of view, the only effect is that a new refs/heads/<new-branch-name>> ref appears. If you want to use the newly created branch, you need to check it out (switch to it) with git checkout.

The newly created branch is not shared by default with any remote repository.

What Happens if There Are Work Tree Changes at the Time of New Branch Creation?

If you start modifying local files and then decide to create a new branch for those modifications, you can simply go ahead and create the branch, check out the new branch and commit the changes on the new branch - the changes will be transferred to the new branch without any complications.

Publish a Local Branch in a Remote Repository

This sections was written with the assumption that the value of 'push.default' is "simple". This is the recommended value, which leads to a more deterministic behavior. For more details see push.default.

Create the Remote Branch and its Local Remote-Tracking Branch

We assume that at this stage, a new local branch exists, created with the procedure described in Create a New Local Branch.

To create a corresponding remote branch, with the same name, and its local remote-tracking branch, execute:

git push <remote-name> <local-branch-name>

Example:

git push origin reference-implementation

In the above example, <local-branch-name> is a degenerate form of +source:destination refspec where only the source ref is specified.

Note that you don't have to be on the branch being pushed while executing the command.

The effect of the command is the creation of a local branch with the specified name (<local-branch-name>) in the remote repository indicated by <remote-name>, the transfer of the refs and objects corresponding to the local branch into the remote repository and the creation of a local tracking-branch, as reflected in the content of the .git/refs/remotes/<remote-name>: a new file with the same name as the local branch appears. The tracking branch is implicitly created.

At this stage, the newly published branch can be tracked: if somebody else clones the upstream repository and updates the newly published branch back in the repository, we're going to get the updates on the tracking branch by running git fetch, which will synchronize the local tracking-branch state with the state of the remote branch, in the remote -> local direction.

git checkout <local-branch-name>
git fetch

However, git fetch will only update the local tracking branch. git pull won't work because even if the tracking branch exists, we did not create yet a link between the local topic branch and the tracking branch so we can merge updates back into the local branch.

git pull
There is no tracking information for the current branch.
Please specify which branch you want to merge with.
...

git push does not work, so the state of the local branch cannot be automatically pushed to the remote repository.

git push
fatal: The current branch reference-implementation has no upstream branch.

This behavior is a consequence of the push.default=simple setting.

The local branch can be linked to the tracking branch as follows.

Link the Local Branch its Tracking Branch

The local branch can be linked to its remote-tracking branch, so both git pull and git push work, as follows:

git branch --set-upstream-to=<remote-name>/<remote-branch-name> <local-branch-name>

Example:

git branch --set-upstream-to=origin/reference-implementation reference-implementation
Branch reference-implementation set up to track remote branch reference-implementation from origin.

Note that you don't have to be on the branch being pushed while executing the command.

The effect of the command is new configuration in .git/config:

...
[branch "reference-implementation"]
        remote = origin
        merge = refs/heads/reference-implementation