Fork Workflow Workshop

Practice the complete fork workflow. This exercise simulates contributing to an open source project.

Overview

You'll:

Fork a repository
Clone your fork
Set up upstream tracking
Create a contribution
Submit a pull request

Exercise 1: Fork and Clone

Option A: Using GitHub CLI


bash
1# Fork and clone in one step
2$ gh repo fork octocat/Spoon-Knife --clone
3✓ Created fork your-username/Spoon-Knife
4Cloning into 'Spoon-Knife'...
5
6$ cd Spoon-Knife

Note: octocat/Spoon-Knife is GitHub's demo repository specifically for practicing forks.

Option B: Manual Process

Go to https://github.com/octocat/Spoon-Knife
Click "Fork" button
Clone your fork:


bash
1$ git clone git@github.com:your-username/Spoon-Knife.git
2$ cd Spoon-Knife

Exercise 2: Configure Remotes

Check Current Remotes


bash
1$ git remote -v
2origin  git@github.com:your-username/Spoon-Knife.git (fetch)
3origin  git@github.com:your-username/Spoon-Knife.git (push)

Add Upstream Remote


bash
1$ git remote add upstream git@github.com:octocat/Spoon-Knife.git

Verify Both Remotes


bash
1$ git remote -v
2origin    git@github.com:your-username/Spoon-Knife.git (fetch)
3origin    git@github.com:your-username/Spoon-Knife.git (push)
4upstream  git@github.com:octocat/Spoon-Knife.git (fetch)
5upstream  git@github.com:octocat/Spoon-Knife.git (push)

Exercise 3: Sync with Upstream

Fetch Upstream Changes


bash
1$ git fetch upstream
2From github.com:octocat/Spoon-Knife
3 * [new branch]      main       -> upstream/main

Update Your Main Branch


bash
1$ git checkout main
2$ git rebase upstream/main
3Current branch main is up to date.

Push to Your Fork


bash
1$ git push origin main
2Everything up-to-date

Exercise 4: Create a Contribution

Create a Feature Branch


bash
1$ git checkout -b contribution/add-my-name
2Switched to a new branch 'contribution/add-my-name'

Make Your Change


bash
1# Add your name to a file
2$ echo "- Your Name was here!" >> README.md

Commit the Change


bash
1$ git add README.md
2$ git commit -m "docs: add my name to contributors"
3[contribution/add-my-name abc1234] docs: add my name to contributors
4 1 file changed, 1 insertion(+)

Exercise 5: Push to Your Fork


bash
1$ git push -u origin contribution/add-my-name
2Enumerating objects: 5, done.
3...
4To github.com:your-username/Spoon-Knife.git
5 * [new branch]      contribution/add-my-name -> contribution/add-my-name
6Branch 'contribution/add-my-name' set up to track remote branch 'contribution/add-my-name' from 'origin'.

Exercise 6: Create Pull Request

Using GitHub CLI


bash
1$ gh pr create \
2  --repo octocat/Spoon-Knife \
3  --base main \
4  --head your-username:contribution/add-my-name \
5  --title "Add my name to README" \
6  --body "Adding my name to practice the fork workflow."
7
8Creating pull request for your-username:contribution/add-my-name into main in octocat/Spoon-Knife
9
10https://github.com/octocat/Spoon-Knife/pull/12345

View Your PR


bash
1$ gh pr view --repo octocat/Spoon-Knife

Note: PRs to Spoon-Knife won't actually be merged—it's just for practice.

Exercise 7: Simulate Upstream Update

Let's practice syncing when upstream changes:

Create a Fake Upstream Change

On your fork's main branch:


bash
1$ git checkout main
2
3# Simulate upstream having new content
4$ echo "Upstream change" >> upstream-changes.txt
5$ git add upstream-changes.txt
6$ git commit -m "simulate: upstream change"
7$ git push origin main

Make Your Branch Outdated


bash
1$ git checkout contribution/add-my-name
2# Your branch is now behind main

Sync Process


bash
1# Fetch the latest
2$ git fetch origin
3
4# Rebase onto updated main
5$ git rebase origin/main
6First, rewinding head to replay your work on top of it...
7Applying: docs: add my name to contributors
8
9# Force push the rebased branch
10$ git push --force-with-lease origin contribution/add-my-name

Exercise 8: Clean Up

Delete Local Branch


bash
1$ git checkout main
2$ git branch -d contribution/add-my-name

Delete Remote Branch


bash
1$ git push origin --delete contribution/add-my-name

Optional: Delete Fork

If you want to delete the practice fork:


bash
1$ gh repo delete your-username/Spoon-Knife --yes

Or delete via GitHub Settings → Delete repository.

Workflow Summary


bash
1# One-time setup
2$ gh repo fork org/project --clone
3$ cd project
4$ git remote add upstream git@github.com:org/project.git
5
6# For each contribution
7$ git fetch upstream
8$ git checkout main
9$ git rebase upstream/main
10$ git push origin main
11$ git checkout -b feature/my-change
12# ... make changes ...
13$ git add . && git commit -m "description"
14$ git push -u origin feature/my-change
15$ gh pr create --repo org/project
16
17# Keep PR updated
18$ git fetch upstream
19$ git rebase upstream/main
20$ git push --force-with-lease

Checklist

Forked a repository
Cloned your fork locally
Added upstream remote
Synced main with upstream
Created a feature branch
Pushed branch to your fork
Created PR to upstream repository
Practiced rebasing when upstream updates

Key Takeaway

The fork workflow enables contributions to projects you don't have direct access to. Always keep your fork synced with upstream, and create PRs from feature branches—never from main.