How to Set Upstream Branch in Git

An upstream branch is the remote-tracking branch that a local branch follows. Once the relationship is configured, Git can infer which remote branch to compare with or use for common git pull and git push operations. Choose the command based on whether the remote branch still needs to be published, already exists, or should be checked out locally for the first time.

What an upstream branch does

Tracking connects one local branch to one remote-tracking branch, such as local my-feature-branch to origin/my-feature-branch. It does not merge branches or copy commits by itself. It gives Git a default destination and comparison point, so later pulls and pushes can usually omit the remote and branch arguments.

The remote-tracking branch must be available in your local repository for commands that refer to it. It is refreshed when you fetch from the remote. The examples below use origin as the remote name and my-feature-branch as the branch name; replace them with the names in your repository.

Set upstream while pushing a new branch

If the local branch has not been published yet, you can publish it without configuring tracking by running git push origin my-feature-branch. This pushes the branch to origin, but later pushes still need the remote and branch arguments. To publish the branch and configure tracking in one operation, run git push --set-upstream origin my-feature-branch; -u is the shorter equivalent. Once tracking is set, later pushes can usually omit the remote and branch arguments.

A small formatter can help check the argument order. It prints a command for you to run; it does not invoke Git or publish a branch.

Run this example:

branch = "my-feature-branch"
remote = "origin"
print(f"git push --set-upstream {remote} {branch}")

git push --set-upstream origin my-feature-branch

After running the Git command in your repository, the remote branch is created and the current local branch tracks it. The --set-upstream-to option belongs to git branch; it is not the push option for publishing a new branch.

Set upstream for an existing local branch

When both the local branch and its remote-tracking branch already exist, switch to the local branch and set its upstream with git branch --set-upstream-to=origin/my-feature-branch. The shorthand is git branch -u origin/my-feature-branch.

These forms configure the current local branch. First make sure you are on the branch you intend to connect, for example with git checkout my-feature-branch, and fetch if origin/my-feature-branch is not yet present in your remote-tracking references. This changes the branch relationship without pushing commits.

Create a local branch that tracks a remote branch

If the branch exists on the remote but not in your local repository, create and switch to a local branch from the remote-tracking branch with git checkout -b my-feature-branch origin/my-feature-branch. This established checkout form creates the local branch and sets its upstream to the named remote-tracking branch.

The local name must not already be in use, and the remote-tracking reference must be available. Fetch first if needed. This is different from publishing a new local branch: here, the remote branch is the starting point for the local branch.

Check or remove an upstream branch

Run git status on the local branch to check its relationship with the upstream. When Git can compare both sides, the status can report that the branch is ahead, behind, or has diverged, helping you decide whether to push, pull, or reconcile commits. If status does not show tracking information, confirm that an upstream is configured and that the remote-tracking reference has been fetched.

To stop tracking the remote branch, run git branch --unset-upstream while on the local branch. This removes only the tracking relationship; it does not delete the local branch, remote branch, or commits. You can set a different upstream later with git branch --set-upstream-to=<remote>/<branch>.