Syncing Your Fork: How to Manage Upstream Changes in Git

Previously in this course, we discussed Introduction to Forking, which covered how to create a personal copy of a project on GitHub. While forking is a great way to start contributing, it creates a static snapshot of the original project. If the original maintainers keep pushing updates, your fork will quickly become outdated.

This lesson focuses on the technical workflow to sync your fork, ensuring your local environment remains current with the original project's progress.

The Concept of Upstream

In a forked workflow, you have two primary remotes:

1. origin: Your personal copy of the repository on GitHub.
2. upstream: The original repository you forked from.

Git does not know about the upstream remote by default. You must explicitly tell your local repository where the original project lives so you can pull its latest updates. Think of this as establishing a "read-only" pipeline from the source of truth to your machine.

Adding the Upstream Remote

To sync your fork, start by verifying your current remotes. Open your terminal in your project directory and run:

Bash
git remote -v

You will likely see only origin. To link the original project, use the git remote add command followed by the URL of the original repository (not your fork):

Bash
git remote add upstream https://github.com/ORIGINAL_OWNER/ORIGINAL_REPO.git

Now, when you run git remote -v again, you will see both origin (for pushing your work) and upstream (for pulling their updates).

Fetching and Merging Changes

Syncing is a two-step process: first, you retrieve the data, and then you integrate it into your work.

1. Fetch the updates

git fetch upstream downloads all the branches and commits from the original repository without altering your current files. It’s a safe, non-destructive operation.

2. Merge the updates

Once fetched, you need to merge those changes into your local main branch:

Bash
git checkout main
git merge upstream/main

If you have local changes that conflict with the upstream updates, Git will pause and ask you to resolve them, much like you learned in Handling Merge Conflicts.

Hands-on Exercise

1. Navigate to your terminal and enter your project folder.
2. Run git remote add upstream [URL_OF_ORIGINAL_PROJECT].
3. Fetch the latest updates: git fetch upstream.
4. Merge the upstream main branch: git merge upstream/main.
5. If the merge was successful, push the updated main branch to your own fork: git push origin main.

Common Pitfalls

• Confusing Origin and Upstream: Always remember: you push to origin (your repo) and pull/fetch from upstream (the source). Never try to push to upstream unless you have explicit write access to the original project.
• Forgetting to Fetch: If you try to merge upstream/main without running git fetch upstream first, you might be merging outdated information from the last time you checked. Always fetch first.
• Syncing on a Feature Branch: Avoid syncing while working on a feature branch unless absolutely necessary. It is safer to sync your main branch, then merge main into your feature branch.

FAQ

Q: Do I need to sync every day? A: Only when you are actively preparing to submit a contribution. If you are working on a long-running feature, syncing once a week or before you start a new task is usually sufficient.

Q: What if I accidentally deleted my local main branch? A: Because your origin is a backup, you can always re-clone your fork or reset your local main to track origin/main.

Q: Is upstream a special keyword in Git? A: Not strictly. It is a community convention. You could name it original-project, but upstream is the standard term used by developers worldwide.

Recap

Staying in sync is a critical skill for collaborative development. By adding an upstream remote and performing regular fetch and merge operations, you prevent "drift" between your code and the project's evolution. This ensures that when you eventually submit your work, it is based on the most recent version of the codebase.

Up next: Creating Pull Requests — where we will take your synced code and propose your changes to the project maintainers.