How to set an upstream branch in Git

To push a new branch and set its upstream, run `git push -u origin my-branch`. If the branch already exists on the remote, run git branch -u origin/my-branch instead. After that, plain git push and git pull know where to go. -u is short for --set-upstream.

What is an upstream branch in Git?

The upstream, also called the tracking branch, is the remote branch linked to your local one. Git uses that link for three things: where git pull and git push go without arguments, what the ahead and behind counts in git status compare against, and what the shorthand @{u} means.

How do I set the upstream for a new branch?

git switch -c feature/search
git push -u origin feature/search

This creates the branch on the remote and links the two. You only need -u on the first push. The create and switch branches guide covers the step before this one.

How do I set the upstream for an existing branch?

When the remote branch already exists, link it without pushing:

# the branch you are on
git branch -u origin/feature/search

# any other branch
git branch -u origin/main main

The long form is git branch --set-upstream-to=origin/main. If Git says the remote branch does not exist, run git fetch first.

How do I fix “The current branch has no upstream branch”?

Git prints this when you run git push on a branch that has never been pushed:

fatal: The current branch feature/search has no upstream branch.
To push the current branch and set the remote as upstream, use

    git push --set-upstream origin feature/search

Run the command it suggests. To stop seeing the error, have Git do this on every first push (Git 2.37 or later):

git config --global push.autoSetupRemote true

The related message “There is no tracking information for the current branch” comes from git pull. The fix is the same: git branch -u origin/my-branch.

How do I see what a branch tracks?

# every branch, with its upstream and ahead/behind
git branch -vv

# only the current branch
git rev-parse --abbrev-ref @{u}

# commits you have not pushed
git log @{u}..

# commits you have not pulled
git log ..@{u}

How do I change or remove an upstream?

# point the branch somewhere else
git branch -u origin/develop

# stop tracking anything
git branch --unset-upstream

Neither command changes any commits. They only edit the branch’s settings in .git/config.

What does upstream mean on a fork?

The word has a second meaning. On a fork, upstream is by convention the name of a remote: the original project you forked from, while origin is your own copy. That is what “git remote add upstream” is about:

git remote add upstream https://github.com/original/project.git
git fetch upstream
git switch main
git merge upstream/main
git push origin main

See set tracking and publish a branch for the details, and the remotes and upstreams lesson to practise.