✅ Best Practices for Keeping a Forked Repository in Sync with Upstream

Maintaining an up-to-date fork while making your own contributions can be challenging. Below are the best practices and methods to keep your fork synchronized without introducing unnecessary merge commits or conflicts.

🔄 1️⃣ Git CLI Approach (Manual Syncing)

The cleanest and most efficient way to update your fork is by using Git’s command-line tools.

Step-by-Step Process:

1. Add the Upstream Repository (If Not Already Added)

git remote add upstream https://github.com/original-repo-owner/original-repo.git

Check if it’s added using:

git remote -v

2. Fetch Latest Changes from Upstream

git fetch upstream

3. Checkout Your Main Branch (e.g., main or master)

git checkout main

4. Merge or Rebase the Changes

• Option 1: Merge (Creates a Merge Commit)

  git merge upstream/main

• Option 2: Rebase (Cleaner History, No Extra Merge Commit)

  git rebase upstream/main

5. Push the Updated Branch to Your Fork

git push origin main

🔹 When to Use Rebase vs. Merge?

• Use rebase if you want a clean, linear history.
• Use merge if you prefer to keep a history of all merges.

🔄 2️⃣ Syncing Using GitHub UI & GitHub CLI

If you don’t want to use the Git CLI, GitHub provides UI and CLI methods.

GitHub UI (For Simple Syncing)

1. Go to your forked repository on GitHub.
2. Click "Fetch upstream" (next to the "Sync fork" button).
3. Click "Update branch" (if there are no conflicts).

⚠️ This method works only if your fork has no conflicting changes. If you’ve made modifications, use Git CLI or rebase instead.

GitHub CLI (gh Command)

If you use the GitHub CLI, you can update your forked repository easily:

gh repo sync <your-username>/<your-forked-repo> --branch main

This fetches and merges upstream changes into your fork automatically.

🤖 3️⃣ Automating Sync with GitHub Actions

To automate keeping your fork updated, you can use GitHub Actions. This workflow automatically syncs the fork with the upstream repository every day.

📝 GitHub Action Workflow (sync-fork.yml)

name: Sync Fork with Upstream
on:
  schedule:
    - cron: '0 0 * * *'  # Runs daily at midnight UTC
  workflow_dispatch:  # Allows manual triggering

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Forked Repository
        uses: actions/checkout@v3
        with:
          token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}

      - name: Add Upstream Remote
        run: git remote add upstream https://github.com/original-repo-owner/original-repo.git

      - name: Fetch Upstream Changes
        run: git fetch upstream

      - name: Merge Changes and Push
        run: |
          git checkout main
          git merge upstream/main
          git push origin main

🔹 Note: You'll need to create a Personal Access Token (PAT) in GitHub and store it in your repo secrets as PERSONAL_ACCESS_TOKEN to allow the workflow to push updates.

🎯 Best Practices for Keeping a Fork in Sync

✅ Use rebase instead of merge for a cleaner commit history.
✅ Always pull upstream changes before making new PRs to avoid conflicts.
✅ Automate syncing if your fork needs frequent updates (e.g., using GitHub Actions).
✅ Delete outdated branches after merging them to keep the repository clean.
✅ Use feature branches for new contributions instead of working directly on main.