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

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

If you are working on a fork of an open-source project or an organization's central repository, you will frequently need to pull down updates from the original source. This setup is the most common workflow for individuals contributing to open-source projects, where you do not have direct write access to the primary codebase and instead submit contributions via Pull Requests from your fork.

Here is a quick guide on how to safely switch to your main branch, check for updates, and sync your fork with the upstream repository—all while keeping your local uncommitted work intact.

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:

  ┌─────────────────────────────────────────────────────────┐
  │              Upstream (Original Source Repo)            │
  └────────────────────────────┬────────────────────────────┘
                               │
                               │ Fork on GitHub
                               ▼
  ┌─────────────────────────────────────────────────────────┐
  │                 Origin (Your Forked Repo)               │
  └────────────────────────────┬────────────────────────────┘
                               │
                Clone          │           Push &
                Locally        │           Pull Request
                               ▼
  ┌─────────────────────────────────────────────────────────┐
  │                Local Machine (Your Workspace)           │
  └────────────────────────────┬────────────────────────────┘
                               │
                               │  git pull upstream main
                               ▼
                     (Syncing directly to Local)

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:

# Fetch updates from all remotes
git fetch --all

# Switch to the main branch
git checkout main

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 main

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