How to git fetch upstream

Greg Foster
Greg Foster
Graphite software engineer


Note

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


In Git, it's important to keep your forked repositories up to date with the upstream repository (the original repository from which the fork was created). This guide will explain the concept of "upstream" in Git, and provide detailed instructions on how to effectively use git fetch to synchronize your fork with the upstream repository. We will also discuss common issues and how to resolve them.

Upstream in Git refers to the main repository from which a fork is taken. When you fork a repository, essentially, you create a copy of the original repository (upstream) under your GitHub profile or another namespace, allowing you to make changes without affecting the original codebase.

The terms "upstream" and "origin" are used to specify remote repositories in Git:

  • Origin: Typically refers to your repository that you cloned from your own account.
  • Upstream: Refers to the original repository from which you forked.

Maintaining a link to the upstream repository allows you to pull changes made in the original project into your fork, ensuring that your repository stays current with the ongoing developments.

Before you can fetch changes from the upstream repository, you need to configure it as a remote in your local Git setup if it's not already configured:

Terminal
git remote add upstream <upstream-repo-url>

Replace <upstream-repo-url> with the URL of the original repository. You can find this URL on the GitHub page of the original repository. This points your local repository at the online, remote repository hosted at the specified URL.

To synchronize your fork with the upstream repository, follow these steps:

  1. Fetch the upstream changes

    Fetching upstream changes downloads the commits, files, and refs from the upstream repository into your local repository but does not merge them into your current branch.

    Terminal
    git fetch upstream

    This command fetches all branches from the upstream repository. If you only need to fetch changes from a specific branch, such as master or main, you can specify that branch:

    Terminal
    git fetch upstream main
  2. Checkout your local branch

    Switch to the branch that you want to sync with the upstream changes. For example, if you are updating your local main you'd run:

    Terminal
    git checkout main
  3. Merge the changes

    After checking out your branch, merge the changes from the upstream branch into your local branch with:

    Terminal
    git merge upstream/main

    This command merges the fetched upstream main changes into your currently checked-out main branch. Now your local repository has the latest changes from the upstream remote repository that the repo was originally forked from.

  4. Push the Changes to Your Origin

    Once the merge is successful and you have resolved any conflicts, push the changes to your repository:

    Terminal
    git push origin main

    This pushes the most recent updates that we just fetched from the upstream remote repo into the remote of your forked repo

  • git fetch upstream not working: Ensure that you have correctly set the upstream repository. Verify by running git remote -v. If it's not configured, add it using the git remote add command shown above.
  • git fetch not getting the latest commit: Check your network settings or permissions to access the upstream repository. Make sure the branch names are correctly specified.
  • git checkout branch from fork: Make sure the branch exists on your fork. If not, you might need to fetch and checkout the branch as new from upstream:
    Terminal
    git fetch upstream <branch-name>
    git checkout -b <branch-name> upstream/<branch-name>
  • Fetching a specific file: Git does not support fetching a specific file from a remote. Instead, you would need to fetch the entire branch and then checkout the specific file.
  • Dry run: While git fetch does not directly support a dry run, you can use git fetch --dry-run to simulate fetching without actually downloading anything.
  • Fetching by SHA: Fetching by a specific commit SHA isn't directly supported in standard Git operations. This typically requires fetching the branch and then checking out the specific commit.

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