git-fork-workflow

Git Fork Workflow

Expert guidance for managing forked repositories, synchronizing with upstream, and contributing back cleanly.

When to Use This Skill

Use this skill when...	Use git-upstream-pr instead when...
Understanding fork remote architecture	Ready to submit a PR to upstream
Diagnosing fork divergence from upstream	Need step-by-step PR creation workflow
Syncing fork's main with upstream	Cherry-picking specific commits for upstream
Deciding on a sync strategy	Creating a cross-fork PR via gh CLI

Remote Architecture

Forks use two remotes:

Remote	Points To	Purpose
origin	Your fork (you/repo)	Push your work here
upstream	Original repo (owner/repo)	Pull updates from here

Setup

# Verify remotes
git remote -v

# Add upstream if missing
git remote add upstream https://github.com/owner/original-repo.git

# Verify
git fetch upstream
git remote -v

Identifying Fork vs Upstream

# Check if upstream remote exists
git remote get-url upstream

# Get fork owner
git remote get-url origin | sed -E 's#.*github\.com[:/]##; s#\.git$##'

# Get upstream owner
git remote get-url upstream | sed -E 's#.*github\.com[:/]##; s#\.git$##'

The Divergence Problem

When you squash-merge branches into your fork's main, the commit SHAs differ from upstream's commits. This creates divergence even when the code content is identical.

Detecting Divergence

# Fetch latest from both remotes
git fetch origin
git fetch upstream

# Count ahead/behind
git rev-list --left-right --count upstream/main...origin/main

# Show divergent commits
git log --oneline upstream/main..origin/main   # Commits on fork not on upstream
git log --oneline origin/main..upstream/main   # Commits on upstream not on fork

Reading the Output

git rev-list --left-right --count upstream/main...origin/main returns two numbers:

Output	Meaning
0 0	Perfectly in sync
5 0	Fork is 5 behind upstream (upstream has 5 new commits)
0 3	Fork is 3 ahead (fork has 3 commits not on upstream)
5 3	Diverged: upstream has 5 new, fork has 3 unique

Sync Strategies

Strategy 1: GitHub CLI Sync (Simplest)

# Syncs fork's default branch with upstream via GitHub API
gh repo sync owner/fork-repo

# Then pull locally
git pull origin main

Best when: fork has no unique commits worth preserving on main.

Strategy 2: Fast-Forward Merge (Clean Canary)

git fetch upstream
git merge --ff-only upstream/main

Best when: fork's main has not diverged. Fails cleanly if diverged (no messy merge commits).

Strategy 3: Hard Reset (Force Sync)

git fetch upstream
git reset --hard upstream/main
git push --force-with-lease origin main

Best when: fork's main has diverged and you want to discard fork-only commits. Destructive - ensure no unique work is on main.

Strategy 4: Rebase (Preserve Fork Work)

git fetch upstream
git rebase upstream/main
git push --force-with-lease origin main

Best when: fork has unique commits on main that should sit on top of upstream's history.

Strategy Selection

Situation	Strategy
Fork main is clean, no unique commits	Fast-forward or gh repo sync
Fork main diverged, unique work expendable	Hard reset
Fork main diverged, unique work worth keeping	Rebase
Just want to match upstream exactly	Hard reset
Not sure	Try fast-forward first; it fails safely if diverged

Golden Rule for Upstream PRs

Branch from upstream/main, not from your fork's main. This completely bypasses fork divergence:

git fetch upstream
git switch -c feat/my-contribution upstream/main
# Cherry-pick, code, or apply changes here
git push -u origin feat/my-contribution
# Create cross-fork PR targeting upstream

See git-upstream-pr for the complete workflow.

Cross-Fork PR Syntax

# Create PR from fork branch to upstream repo
gh pr create \
  --repo owner/upstream-repo \
  --base main \
  --head your-username:feat/branch-name \
  --title "feat: description" \
  --body "PR description"

The --head must include the fork owner prefix (your-username:branch) when targeting a different repository.

Common Patterns

Check if Working in a Fork

# Has upstream remote = likely a fork
git remote get-url upstream 2>/dev/null && echo "Fork" || echo "Not a fork"

Periodic Sync Workflow

# Weekly sync routine
git fetch upstream
git switch main
git merge --ff-only upstream/main || echo "Diverged - manual sync needed"
git push origin main

View Upstream Changes Since Last Sync

git fetch upstream
git log --oneline origin/main..upstream/main

Agentic Optimizations

Context	Command
Divergence count	git rev-list --left-right --count upstream/main...origin/main
Fork ahead commits	git log --oneline --format='%h %s' upstream/main..origin/main
Fork behind commits	git log --oneline --format='%h %s' origin/main..upstream/main
Quick sync check	git fetch upstream && git merge --ff-only upstream/main
Remote listing	git remote -v

Related Skills

• git-upstream-pr - Submit clean PRs to upstream repositories
• git-branch-pr-workflow - General branch and PR workflow patterns
• git-rebase-patterns - Advanced rebase techniques
• git-conflicts - Resolve cherry-pick and merge conflicts
• git-repo-detection - Remote URL parsing patterns