How to Set Upstream Branch in Git
Short answer
Setting an upstream (tracking) branch links your local branch to a specific branch on a remote, allowing git pull and git push to work without requiring you to type the remote name and branch name each time. To set the upstream for the current branch after it already exists locally, run git branch --set-upstream-to=origin/<remote-branch>. The most common way to set upstream at push time is git push -u origin <branch-name>, which pushes and configures the tracking relationship in a single command. Once tracking is configured, git status reports how many commits ahead or behind the remote your local branch is, helping you stay aware of divergence before pushing or pulling. Run git branch -vv to see all local branches with their configured upstream and the current ahead/behind count at a glance.
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:
-
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".
-
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!
Free. We email you a ZIP with our cheat sheets.
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 – Desktop GUI edition in our free online book