Git: Set the Upstream Branch
Last updated
A branch's upstream is the remote branch it tracks. Once it's set, a plain git push and git pull know where to send and fetch commits without you naming the remote and branch each time. You usually set it on the first push with -u, or later with git branch --set-upstream-to.
Try these in the terminal playground - a real shell in your browser, nothing to install.
Syntax
| Command | What it does |
|---|---|
git push -u origin feature | Push and set upstream in one step |
git branch --set-upstream-to=origin/feature | Set upstream for the current branch |
git branch -u origin/feature feature | Set upstream for a named branch |
git branch -vv | Show each branch and its upstream |
Common cases
| Goal | Command |
|---|---|
| Set upstream on first push | git push -u origin feature |
| Set upstream for an existing branch | git branch --set-upstream-to=origin/feature |
| Check which upstream is set | git branch -vv |
Git set upstream FAQ
What does setting the upstream branch do?
It links your local branch to a specific remote branch. After that,
git push and git pull on that branch know the remote and branch to use, so you can run them without arguments. Git also shows how far ahead or behind the upstream you are in git status.How do I set the upstream branch?
The easiest way is on the first push:
git push -u origin <branch> pushes and sets the upstream at once. For a branch that already exists on the remote, use git branch --set-upstream-to=origin/<branch> while on that branch.How do I see a branch's upstream?
Run
git branch -vv. It lists your local branches, each annotated with its upstream (like [origin/feature]) and whether it's ahead or behind. Branches with no upstream show nothing in brackets.Why does git push ask me to set the upstream?
Because the current branch has no upstream configured, so Git doesn't know where to push. Run
git push -u origin <branch> once to set it; subsequent pushes need only git push.Can I practice this online?
Yes. Open the terminal playground to run these commands in a real shell in your browser - nothing to install. Coddy's free interactive Git course also covers working with remotes step by step.
Related resources
More Git commands
