Syncing a fork with the upstream repository 🔄

When you fork a project, your copy is frozen at the moment of forking. The original project keeps moving — other developers’ PRs get merged into it. To work with up-to-date code, you need to sync your fork periodically.

Why your fork falls behind

Fork moment:    original: A──B──C
                your fork: A──B──C  (copy)

Later:          original: A──B──C──D──E──F  (D, E, F added)
                your fork: A──B──C──X──Y     (you added X, Y)

Your fork has no idea that commits D, E, F exist until you sync it.

When to sync

• Before starting a new task — so you’re working with current code
• When a PR shows a conflict — the upstream changed while you were working
• Periodically — if the project is actively developed

Method 1: The Sync fork button on GitHub (easiest)

Step 1: Open your fork on GitHub

URL: github.com/YOUR-USERNAME/repo-name

Step 2: Make sure you’re on the main branch

Switch to main if needed.

Step 3: Find the Sync fork button

Below the Code button you’ll see a status message:

“This branch is N commits behind original:main”

Next to it is the Sync fork button.

Step 4: Update the branch

Click Sync fork → Update branch.

GitHub will automatically pull new commits from upstream and add them to your fork.

What if there’s no button?

The Sync fork button only appears when your fork is behind the upstream. If it’s not there, your fork is already current — nothing to do.

Method 2: GitHub Desktop

After syncing your fork on GitHub (steps above), update your local copy:

1. Switch to the main branch in GitHub Desktop
2. Click Fetch origin
3. Click Pull origin

Your local main now matches the upstream.

Update your working branch

After syncing main, update your working branch as well:

In GitHub Desktop:
1. Switch to your branch (e.g. feature/guide-kazan)
2. Branch → Update from default branch (or “Merge into current branch” → select main)

If your changes touch the same files as new upstream commits, a conflict will occur. Resolve it: Resolving merge conflicts.

Syncing via the command line

For those who prefer the terminal:

# One-time setup: add the upstream repo as a remote
git remote add upstream https://github.com/ORIGINAL-AUTHOR/repo-name.git

# Each time you sync:
git fetch upstream          # fetch changes from upstream
git checkout main           # switch to main
git merge upstream/main     # merge upstream changes
git push origin main        # update your fork on GitHub

Sync and PR conflicts

The most common scenario:

1. You forked the repo and started working
2. Another PR was merged into upstream — it changed the same file you’re working on
3. Your PR now shows a conflict

How to fix it:

1. Sync fork on GitHub (update main in your fork)
2. Fetch + Pull in GitHub Desktop (update local main)
3. Branch → Update from default branch (update your branch)
4. Resolve the conflict in your editor
5. Commit + Push
6. The PR updates automatically — the conflict disappears

Why you don’t need to open a new PR

After syncing and resolving the conflict, your existing PR updates automatically. There’s no need to open a new one.

Keeping your fork in sync regularly

If you’re working on a long-running task in an active project:

Start of work:  sync your fork
Every 2–3 days: sync your fork and update your branch
Before a PR:    make sure your fork is current

This reduces the number of conflicts and makes them easier to resolve.