In this lesson, you will learn how to bridge the gap between your local fork and the original "upstream" repository to keep your development work aligned with the maintainer's latest updates.
When you fork a repository on GitHub, you create a remote copy under your own account. However, the original repository (the "upstream") continues to evolve independently. If you only pull from your own fork (origin), you will eventually fall behind the project's official codebase. To stay current, you need to inform your local Git environment about the existence of that original repository.
Configuring the Upstream Remote
Think of your local Git configuration as a map. Currently, it knows about origin (your fork). To synchronize, we must add a second reference pointing to the source repository:
git remote add upstream https://github.com/ORIGINAL_OWNER/ORIGINAL_REPO.git
Once added, you can fetch the latest work from the maintainers without merging it immediately. This allows you to inspect the changes first:
git fetch upstream
Merging Upstream Changes
After fetching, your local environment has the latest code from the upstream repository stored in upstream/main (or the relevant default branch). To update your local development branch, you must merge these changes:
git checkout main
git merge upstream/main
By performing these steps regularly, you prevent "drift." If you don't synchronize, you risk encountering massive merge conflicts later when you finally try to contribute your features back to the project. Keeping your local branch in sync with upstream ensures that your development happens on a foundation identical to what the maintainers are currently using.
If you encounter a conflict during this merge, use the skills you learned in our previous lessons on resolving conflict markers to align your work with the official project direction. Once your local main is updated, remember to push those changes back to your fork (git push origin main) to keep your GitHub-hosted fork current as well.
Key Takeaway: Adding an upstream remote allows you to fetch and merge changes from the source repository, ensuring your local work stays compatible with the official project codebase.