Keep Your Fork In Sync: Understanding git remote upstream

#beginners #tutorial #git

When you fork a repository on GitHub to contribute to an open-source project or keep a copy for your work, it's important to be able to sync your local fork with updates made in the original repository. That's where adding a remote upstream comes in handy.

In this post, I'll explain what git remote upstream is, why it's useful, and provide examples of how to set it up and use it to keep your fork in sync.

What is a remote upstream?

By default, when you fork a repository your local clone will only have a remote called origin configured, which points to your forked repository on GitHub. While the origin allows you to push/pull with your fork, it doesn't connect you back to the source project repository.

That's where adding an upstream remote comes in. upstream allows you to fetch changes made in the original repository without pushing any updates back. It serves as a read-only path to the source project.

source

Setting up remote upstream

To set up an upstream remote on your local fork, you need to get the clone URL of the original repository:

git remote add upstream https://github.com/ORIGINAL_OWNER/REPOSITORY.git
git remote set-url --push upstream DISABLE  # so that you don't push back to the original repo

You can verify it was added correctly with git remote -v:

origin  https://github.com/<your_username>/<repository>.git (fetch)
origin  https://github.com/<your_username>/<repository>.git (push)
upstream    https://github.com/ORIGINAL_OWNER/REPOSITORY.git (fetch) 
upstream    https://github.com/ORIGINAL_OWNER/REPOSITORY.git (push)

Using remote upstream

Now you have two remotes configured:

origin points to your fork
upstream points to the original repo

To sync changes from upstream to your local fork, you can fetch and merge the upstream branch

# Fetch the latest changes 
git fetch upstream

# Merge upstream changes into your active branch
git merge upstream/main

This will bring any commit made from the original repo into your local fork, allowing you to work seamlessly with the latest updates.

And with that, you now have a shortcut configured to easily keep your fork in sync with the original project source! Let me know if any part needs more explanation.