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:

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

The Sync Workflow

Here is the step-by-step process of adding the upstream remote, stashing local changes, pulling the source updates, and restoring your work.

Step 1: Add the Upstream Remote (One-time setup)

To pull updates from the original source repository, you need to configure a remote called upstream that points to the original parent repository on GitHub.

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

Verify your remotes are set up correctly:

git remote -v
# Output should show 'origin' (your fork) and 'upstream' (the original source)

Step 2: Fetch Remote Metadata & Switch Branch

Fetch all branches from both your fork (origin) and the source (upstream) to make sure your local cache is updated:

# Fetch latest commits from all remotes
git fetch --all

Check out your local main branch (e.g. master or main):

# Switch to the main branch
git checkout master

Step 3: Stash Local Modifications (Safety First)

If you have uncommitted changes in your workspace (such as local configuration files, environment tweaks, or debug profiles), merging changes might cause conflicts.

Save them safely to Git's stash memory:

# Temporarily stash local changes
git stash

This clears your working directory so you can perform the sync smoothly.

Step 4: Pull and Sync from Upstream

Sync your local main branch with the upstream source's main branch:

# Pull upstream changes into your current local branch
git pull upstream master

If your local branch was already up-to-date with upstream, Git will output Already up to date. If there are new commits, they will be cleanly integrated.

Step 5: Restore Your Local Modifications

Bring back the local work you stashed in Step 3:

# 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