How to Set Upstream Branch in Git

In theory, local and remote branches in Git are completely separate items. In practice, however, in makes lots of sense to see them as counterparts - connected in a so-called "tracking connection".

Why should you set up an upstream branch for a local branch?

Let's say that your current local HEAD branch is named "development". Let's also say that you've set the remote "origin/development" as its upstream branch. This relationship is very helpful for two reasons:

1. Push and pull become a lot easier. With an upstream branch set, you can simply use the shorthand commands "git pull" and "git push" - instead of having to think about the exact parameters like in "git push origin development".

2. Git can now also tell you about unsynced commits which you haven't pushed or pulled, yet. Here's an example:

(a) if you have 2 commits in your local repository which you haven't pushed to the remote yet, then your local branch is "2 commits ahead" of its upstream branch.
(b) if there are 4 commits on the remote upstream branch which you haven't pulled yet, then your local branch is "4 commits behind" its upstream branch.

This information helps tremendously in staying up-to-date. Git tells you about this right in the output for "git status":

  $ git status
  # On branch development
  # Your branch and 'origin/development' have diverged,
  # and have 2 and 3 different commits each, respectively.
  #
  nothing to commit (working directory clean)
  

Setting an Upstream Branch

The easiest way to set an upstream branch is to use the "--set-upstream" option when pushing the branch to the remote repository for the first time:

$ git push --set-upstream origin <branch>

A shorter synonym is the "-u" option (instead of the self-explaining but clunky "--set-upstream"):

$ git push -u origin <branch>

If the remote counterpart branch already exists or if you want to change the upstream branch, you can use the "git branch" command:

$ git branch -u origin/<branch>

If you're using the Tower Git client, you don't have to do anything: Tower will automatically set the upstream when you publish a local branch. It will even inform you about any commits that you haven't pushed or pulled, yet:

Learn More

• Check out the chapter Inspecting Remote Data in our free online book
• More frequently asked questions about Git & version control