Fork & Upstream Workflow

Why Fork?

Forking creates a server-side copy of a repository under your own account. This is the standard way to contribute to open source projects where you don't have write access to the original repository. You make changes in your fork and then submit a pull request back to the upstream project.

Forking is also useful in enterprise settings where you want to customize a library or maintain a diverged version without affecting the original. It gives you complete control over your copy while keeping a clear link to the source.

Forking Setup

After forking a repository on GitHub, you need to clone your fork locally and configure the upstream remote. This two-remote setup — origin pointing to your fork, upstream pointing to the original — is the foundation of the forking workflow.

git clone https://github.com/YOUR-USER/awesome-project.git
cd awesome-project
git remote -v

git remote add upstream https://github.com/ORIGINAL-OWNER/awesome-project.git
git remote -v

Keeping Your Fork Synced

The upstream repository evolves constantly. To keep your fork current, you fetch from upstream and merge or rebase the changes into your local main branch. Then push the updated main to your fork.

git fetch upstream
git checkout main
git merge upstream/main
git push origin main

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

git fetch --prune origin
git branch -d feature/old
git push origin --delete feature/old

Contributing via Fork

The standard contribution flow for open source: sync your fork, create a feature branch, make changes, push to your fork, and open a PR against the upstream repository.

# 1. Sync your fork
git fetch upstream
git checkout main
git merge upstream/main

# 2. Create a feature branch
git checkout -b fix/null-pointer

# 3. Make changes and commit
git add .
git commit -m "fix: handle null user in auth middleware"

# 4. Push to your fork
git push origin fix/null-pointer

# 5. Create PR against upstream
gh pr create \
  --repo ORIGINAL-OWNER/awesome-project \
  --title "Fix null pointer in auth middleware" \
  --body "Fixes #301"

Using gh repo fork

GitHub CLI can fork a repository and clone it in one command, automating the setup that would otherwise require multiple manual steps.

gh repo fork ORIGINAL-OWNER/awesome-project --clone

gh repo fork ORIGINAL-OWNER/awesome-project --clone=false

Fork vs Branch Workflow

Both workflows achieve the same goal — enabling code review before merging — but they differ in access control, complexity, and trust model.