If you like surprises from git then by all means ignore upstreams and live dangerously. If you prefer your pushes and pulls to go where you expect then set an upstream and cure the chaos. This quick guide shows how to link a local branch to a remote branch so daily git push and git pull behave like a professional tool and not a rogue art project.

Quick steps to set an upstream

Step 1 Create a local branch

Start a feature or a fix with a branch. You can make the branch and switch to it in one go or in two steps depending on your mood and terminal history.

git branch feature-branch
# or
git checkout -b feature-branch

Step 2 Push and set upstream

Push the branch to the remote and teach git where to send future pushes and pulls. The flag -u tells git to remember the remote branch as the upstream tracking branch.

git push -u origin feature-branch

After that you can run git push and git pull without typing the remote and branch name and fewer mistakes will be made. That is the whole point.

Step 3 Verify tracking status

Want proof that you did it right or that your teammate did not sabotage your branch naming? Use one of these commands.

• git status -sb shows a compact status and shows the remote tracking name
• git branch -vv lists local branches with their upstream and how far ahead or behind they are

Step 4 Change upstream when the remote name or target changes

If the remote branch gets renamed or you need to point your local branch at a different remote branch do not delete the branch and cry. Use this command to rewire the tracking target.

git branch -u origin/other-branch feature-branch

This is handy when you rebase and want to map the updated local branch to an existing remote branch or when you are moving a feature between remotes.

Step 5 Use upstream tracking for day to day workflow

Once upstream is set you get to be lazy in a productive way. Use plain git pull and git push with no extra arguments for most work. Fewer keystrokes means fewer chances to push to the wrong place which is the true hazard of modern development.

Common mistakes and how to survive them

• Forgetting to push with -u the first time and then pushing to the wrong branch. Fix by running git push -u origin feature-branch or run git branch -u origin/feature-branch feature-branch.
• Seeing unexpected upstream names in git branch -vv. That usually means the branch was created differently. Repoint with git branch -u.
• Pushing to the wrong remote because you have multiple remotes. Use git remote -v to inspect remotes and then push explicitly once to set the expected upstream.

Quick troubleshooting tips

If you are unsure where a branch points run git branch -vv and read the rightmost column. If the branch has no upstream the column will be empty and git will ask for a destination when you push. If git refuses to push after you rebase you might need to force push depending on your workflow and team rules. Do not force push unless you enjoyed asking for trouble and then apologizing in pull request comments.

Setting upstreams is a small amount of discipline that saves a ton of accidental merges and awkward git apologetic messages. Keep your branch management tidy and your developer workflow marginally less painful.