How to Sync a Forked Git Repository (Without Losing Local Changes)

Understanding Remotes: Origin vs. Upstream

When working with a Git fork, your project interacts with two different remote locations on GitHub:

• origin: This points to your personal fork of the repository (e.g., git@github.com:your-username/sundar-gutka-react.git). You have read and write permissions to this remote, meaning you can push branches, make releases, and work directly here.

• upstream: This points to the original source repository that you forked from (e.g., https://github.com/KhalisFoundation/sundar-gutka-react.git). You generally only have read permissions here. You fetch official releases and pull updates from upstream to stay in sync with the central development.

Visualizing the flow:

graph TD
    Upstream["Upstream (Original Source Repo)"] -->|"Fork on GitHub"| Origin["Origin (Your Forked Repo)"]
    Origin -->|"Clone locally"| Local["Local Machine (Your Workspace)"]
    Local -->|"git pull upstream"| Upstream
    Local -->|"git push origin"| Origin
    Origin -->|"Pull Request"| Upstream

Synchronization Scenarios

How you start the sync depends on whether you have previously configured the original parent repository as a remote on your local machine.

• First-Time Sync: If you just cloned your fork and have never synced it before, start with Step A (Initial Remote Setup) below, and then follow the workflow.
• Subsequent Syncs (Non-First Time): If you have already added the original repo as a remote, you can skip Step A entirely and proceed directly to Step 1 (Stashing Local Work).

Step A: Initial Remote Setup (First-Time Only)

Before you can sync with the original repository, you need to tell Git where it is. You do this by adding a remote pointer, conventionally named upstream:

# Add the original parent repository as 'upstream'
git remote add upstream https://github.com/ORIGINAL_OWNER/ORIGINAL_REPO.git

# Verify that both 'origin' (your fork) and 'upstream' (original source) are listed
git remote -v

Once the upstream remote is configured, you are ready to begin the synchronization workflow.

The Synchronization Workflow (For Both Cases)

Step 1: Stash Local Modifications (Safety First)

If you have uncommitted changes (like customized environment files, API configs, or local settings) in your workspace, pull conflicts can halt your sync. Clear them safely using Git's stash memory:

# Temporarily stash your local uncommitted changes
git stash

Step 2: Fetch Metadata & Switch Branch

Fetch the latest commits and branches from both your fork (origin) and the source (upstream), and switch to your main branch (e.g., master or main):

# Fetch updates from all remotes
git fetch --all

# Switch to the main/master branch
git checkout master

Step 3: Pull Updates from Upstream

Sync your local main branch by pulling down the latest changes directly from the original source's main branch:

# Pull upstream changes into your active branch
git pull upstream master

If your local branch is already up-to-date, Git will return Already up to date. If there are new changes, Git will fast-forward or merge them.

Step 4: Restore Your Local Work

Finally, bring back your local uncommitted work that you stashed in Step 1:

# Apply and delete the latest stashed state
git stash pop

Git will merge your local changes back into the workspace. If there are minor file conflicts, you can resolve them manually.

Quick Reference: Commands Used