Syncing Upstream Repositories and Keeping Forks Updated0%
Shelving Changes Temporarily with git stash (save, pop, apply, drop)

Syncing Upstream Repositories and Keeping Forks Updated

Beginner12 min read•Updated: Jul 11, 2026
Study MaterialsCheatsheet

Syncing Upstream Repositories and Keeping Forks Updated

When contributing to open-source software, hundreds of developers may merge code into the original project every week. If your personal fork falls behind, you will encounter merge conflicts and outdated code. Keeping your fork in sync with the original repository (called upstream) is a vital skill.

1. The Multi-Remote Topology: origin vs upstream

When you work on a fork, your local machine communicates with two different remote repositories:

Output
[ Original Project ] (e.g. github.com/facebook/react)
^
| upstream (read-only for you)
|
[ Your Local Machine ] (D:/projects/react)
|
| origin (your read-and-write fork)
v
[ Your Personal Fork ] (e.g. github.com/sumit-msk/react)
  • origin: Points to your personal fork on GitHub. You have write/push access here.
  • upstream: Points to the original canonical repository. You read/fetch updates from here.

2. Setting Up the upstream Remote

When you first clone your personal fork, Git only knows about origin:

Bash / Terminal
git remote -v
# Output:
# origin git@github.com:sumit-msk/react.git (fetch)
# origin git@github.com:sumit-msk/react.git (push)

Adding the Original Project as upstream:

Bash / Terminal
git remote add upstream git@github.com:facebook/react.git

Verify Both Remotes:

Bash / Terminal
git remote -v
# Output:
# origin git@github.com:sumit-msk/react.git (fetch)
# origin git@github.com:sumit-msk/react.git (push)
# upstream git@github.com:facebook/react.git (fetch)
# upstream git@github.com:facebook/react.git (push)

3. The 4-Step Terminal Sync Workflow

Whenever you sit down to write new code or before opening a PR, sync your local main branch with upstream:

Bash / Terminal
# Step 1: Switch to your local main branch
git switch main
 
# Step 2: Fetch all latest branches and commits from upstream
git fetch upstream
 
# Step 3: Fast-forward merge upstream/main into your local main
git merge upstream/main
 
# Step 4: Push the updated main to your personal GitHub fork (origin)
git push origin main

Your local repository AND your personal fork on GitHub are now 100% up-to-date with the original open-source project!

4. Alternative: GitHub Web UI "Sync Fork" Button

GitHub also provides a convenient web button on your fork's homepage:

  1. 1
    Navigate to your fork repository on GitHub (github.com/your-username/repo-name).
  2. 2
    Under the repository header, look for:

"This branch is 12 commits behind upstream:main".

  1. 1
    Click the Sync fork button -> Update branch.
  2. 2
    Then, pull down the updates to your laptop:
Bash / Terminal
git switch main
git pull origin main
Interactive Quiz

Practice Quiz

Question 1
In open-source Git workflows, what does the remote alias upstream conventionally refer to?
Question 2
What command configures the original repository as an upstream remote?
Question 3
What is the recommended terminal sequence to pull in upstream updates to your local main branch?
Question 4
Why is it crucial to sync your fork before starting work on a new feature?
Question 5
After merging upstream/main into your local main, why should you run git push origin main?
Next Lesson

Shelving Changes Temporarily with git stash (save, pop, apply, drop)

Continue learning with hands-on practice, examples, and exercises in the upcoming topic.

Related Lessons

Previous LessonNext Lesson
Code Reviews, Inline Comments, Approvals and Changes RequestedShelving Changes Temporarily with git stash (save, pop, apply, drop)

Practice Quiz

Test your understanding of this lesson with 5 questions. Each question has one correct answer.

PreviousNext
PrevNext