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

git-fork-workflow