Adding an upstream remote to a forked Git repo

Greg Foster
Greg Foster
Graphite software engineer

This guide will explain what an upstream remote is and how to add one in Git, covering the process in detail to ensure you can manage your fork effectively.

Adding an upstream remote to a forked Git repository allows you to keep your fork synchronized with the original repository, allowing you to fetch the latest changes from the upstream project. This ensures your codebase includes the latest updates and bug fixes. By having an upstream remote, you can easily compare your fork's progress against the source repository, which is useful for spotting deviations or additional features you might have added. It also facilitates easier contribution back to the original project, as you can pull changes from the upstream repository and merge them into your fork before submitting a pull request.

In Git, a "remote" refers to a version of your repository that is hosted on the internet or network somewhere. When you clone a repository, Git automatically sets up a remote named "origin" pointing back to the cloned repository.

In the context of "forking", making a divergent copy of an existing repository, an "upstream" remote typically refers to the original repository from which you forked. When you fork a project, you create a personal copy of the other project. By adding an upstream remote, you link your fork back to the original, enabling you to fetch updates and submit changes.

Once you have your fork on your local machine, the next step is to add the original repository as an upstream remote:

  1. Locate the original repository’s URL: This is typically found on the project’s page on GitHub, Bitbucket, etc.

  2. Add the remote: Use the git remote add command followed by the name you assign to the remote (commonly "upstream") and the URL of the original repository.

    git remote add upstream
  3. Verify the remote: After adding the remote, it’s good practice to verify that it was added correctly.

    git remote -v

    You should see the URL for both 'origin' (your fork) and 'upstream' (the original repository).

With the upstream remote added, you can start using it to keep your fork up to date or to contribute back to the original repository:

  • Fetch updates from the upstream: This downloads updates from the original repository without merging them into your current branch.

    git fetch upstream
  • Merge updates into your branch: After fetching the updates, you might want to merge them into your branch, especially if you are working on contributing a feature or a fix.

    git checkout main # or master, if that's your default branch
    git merge upstream/main # or upstream/master
  • Push updates to your fork: After merging changes from the upstream, push them to your fork to keep it up to date.

    git push origin main # or master
  • Conflicts during merge: If the upstream has diverged significantly from your fork, you might encounter merge conflicts. Resolve these by editing the files manually, and commit the changes.

  • Upstream URL changes: If the original repository’s URL changes (for example, the project is moved to a different username), you will need to update your remote: You can do this by running:

    git remote set-url upstream

When you've made changes to your fork of a project and want to share them with the original repository, you first need to push these changes. This is done using the git push command, which uploads your local branch updates to your remote fork on platforms like GitHub.

  1. Push your changes: Make sure your local repository is up to date with any changes in the original project by fetching and merging them. Then, commit your changes locally to your branch. Use the command git push origin <branch-name>, where <branch-name> is the name of your branch, to push these changes up to your fork on GitHub or another version control platform.

  2. Create a pull request:

    • What is a pull request?: A pull request is a method used in version control systems to initiate a review process for code changes. It's essentially a request to the original repository's maintainers to "pull" your changes into their repository. This begins a discussion and review period where project maintainers and other contributors can comment on the changes and suggest or make further modifications.
    • How to open one: To create a pull request, go to your fork on GitHub (or another platform where your fork is hosted). You’ll often find a “Compare & pull request” button visible on your fork’s main page if recent changes are detected. Click this button. You’ll be prompted to choose the branch in the original repository that you want to compare with your changes.
  3. Fill out the pull request details:

    • Choose the branch from the original repository where you want your changes to be merged. This is typically the main branch.
    • Write a clear title and description for your pull request. This should explain your changes and the reasons for them, providing context for the maintainers and other contributors.
    • Submit the pull request by clicking the "Create pull request" button.
  4. Engage in the discussion: After your pull request is opened, other contributors and maintainers will review your changes and possibly request further modifications. Stay engaged, respond to comments, and make any necessary adjustments. Your changes might be merged once they meet the project's standards and get approval.

After pushing, you would go to your repository page on GitHub, where you can initiate the pull request as described.

Creating and managing pull requests is a core aspect of collaborative software development, allowing for code review and contributions that maintain the quality and integrity of a project.

For further reading on remote branches and forking, 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