How to git fetch upstream

Greg Foster
Greg Foster
Graphite software engineer

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:

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.

    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:

    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:

    git checkout main
  3. Merge the changes

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

    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:

    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:
    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.

Stay unblocked. Ship faster.
Experience the new developer workflow - create, review, and merge code continuously. Get started with one command.
Get started

Give your PR workflow
an upgrade today

Stack easier | Ship smaller | Review quicker

Or install our CLI.
Product Screenshot 1
Product Screenshot 2