Setting an upstream in Git

Kenny DuMez
Kenny DuMez
Graphite software engineer


Note

This guide explains this concept in vanilla Git. For Graphite documentation, see our CLI docs.


An "upstream" branch refers to the default remote branch that Git uses for reading and writing operations. This guide will explain how to set, change, and use upstream branches in your Git workflow.

In Git, the term "upstream" refers to the main branch from which a given branch was branched off of and to which it may eventually push changes to. By default, Git uses "origin" as the remote name for the upstream repository, but you can configure this to any name.

For a more detailed discussion on the differences between "remote" and "local" branches, see this guide comparing branch branch types in Git.

Setting an upstream branch associates your local branch with a branch on a remote repository. This association is crucial for pull and push operations without specifying a particular remote each time.

Before setting an upstream, ensure that the remote repository is added to your local Git configuration. Running this command will list all of the remotes you currently have available:

Terminal
git remote -v

If the necessary remote is not listed, you can add it using:

Terminal
git remote add <remote_name> <remote_url>

If you are creating a new branch and want to set its upstream immediately, use:

Terminal
git checkout -b <branch_name>
git push -u <remote_name> <branch_name>

The -u option with git push sets the upstream for the branch. This means that later you can just use git push or git pull without specifying the remote name and branch.

To set an upstream for an existing local branch, use the following command:

Terminal
git push -u <remote_name> <branch_name>

The -u flag sets the upstream for the branch, which means that future git pull commands executed on that branch will automatically know which remote branch to fetch and merge changes from, and future git push commands will know where to push the changes without specifying the remote and branch names. This simplifies subsequent git operations by establishing a tracking relationship between your local branch and its remote counterpart.

You can also set the upstream for a local branch by running:

Terminal
git branch --set-upstream-to=<remote_name>/<branch_name>

This command explicitly sets the upstream branch to the branch you currently have checked out. To specify a local branch other than the one you are currently on, you can specify the local branch name at the end of this command. The whole command then looks like this:

Terminal
git branch --set-upstream-to=<remote_name>/<branch_name> [local_branch_name]

To view the upstream configured for your current branch or another branch, run:

Terminal
git branch -vv

This command shows all local branches along with more information including their upstream branches if set.

Fetching updates from the upstream branch is important to keep your local repository updated:

Terminal
git fetch <remote_name>

This command pulls down all the new data from the remote repository but doesn't merge any changes into your local branches.

After setting the upstream, pushing changes is straightforward:

Terminal
git push

Since the upstream is set, Git knows where to push the changes without needing to specify the remote and branch.

If you need to change the upstream branch for any reason, you can reset it using:

Terminal
git branch --set-upstream-to=<new_remote>/<new_branch>

This command redefines the upstream for the current branch.

For further reading see the official Git documentation.

Graphite
Git stacked on GitHub

Stacked pull requests are easier to read, easier to write, and easier to manage.
Teams that stack ship better software, faster.

Or install our CLI.
Product Screenshot 1
Product Screenshot 2