Frequently asked questions around Git and Version Control.
Git FAQ featured image

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)

The Git Cheat Sheet

No need to remember all those commands and parameters: get our popular "Git Cheat Sheet" - for free!

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

About Us

As the makers of Tower, the best Git client for Mac and Windows, we help over 100,000 users in companies like Apple, Google, Amazon, Twitter, and Ebay get the most out of Git.

Just like with Tower, our mission with this platform is to help people become better professionals.

That's why we provide our guides, videos, and cheat sheets (about version control with Git and lots of other topics) for free.