Best Practices for Keeping a Forked Repository Up to Date

[MerrickHayes]

Best Practices for Keeping a Forked Repository Up to Date

When working with open-source projects, forking a repository is common. However, keeping the fork in sync with the upstream repository while maintaining our own changes can be tricky.

Challenges:

• How to regularly pull updates from the original (upstream) repository without conflicts?
• How to handle divergent changes if I modify files that also change upstream?
• What’s the best approach for keeping a fork clean while contributing upstream?

[AayushBharti]

✅ 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.

[ghostinhershell]

Thanks so much for helping here @AayushBharti!

[kdraeder]

@AayushBharti thanks for the multipart answer. It seems recent, but part of it doesn't match with what I see, so I'm hoping that you recognize what's happening and have an easy fix. If not, I'll try the other methods.
In "Syncing Using GitHub UI & GitHub CLI" you said '2. Click "Fetch upstream" (next to the "Sync fork" button).'
but I don't see a "Fetch upstream" in my fork (see screenshot), including in the pull-down menus.

[DGDodo]

Unable to update my fork to original ....

[nuri-yoo]

One thing that helps with keeping track of fork sync status is checking it from the terminal before deciding whether to sync. I built branch-watch for this — bw forks shows all your forks vs. upstream at a glance with ahead/behind commit counts, so you can quickly see which ones need attention.

[RebelStreamers]

Not working any method when Fork has a custom Branch attached with extra code on new branch!

git in terminal keeps asking for username and password when there is a custom branch with the old Fork code ...

All these methods above work only when the Fork has not any custom branch and i tested them with other Forks that haven't a custom branch with my code!

Someone to provide a valid solution when there is a custom branch attached to the Fork please ?