Stacked PRs - Machete + GH

stacked-prs.md

Stacked PRs Cheat Sheet: Fork Edition

Tools: git-machete + GitHub CLI (gh)

1. Setup (One-Time)

Install tools and create aliases to speed up the "Draft & Wait" workflow.

# Install Machete
brew install git-machete

# Alias 1: Create a Draft PR (prevents accidental reviews)
gh alias set stack-create 'pr create --draft --base main --label "stacked-pr" --body "Stacked on parent. Do not review yet."'

# Alias 2: Promote a PR (undraft it)
gh alias set stack-promote 'pr ready'

---

2. The Workflow

A. Start the Stack (Coding)

Create your branches normally.

git checkout -b feature-core
git commit -m "feat: core logic"

git checkout -b feature-ui
git commit -m "feat: ui components"

B. Define the Stack

Tell Machete the relationship between branches.

git machete edit

Editor opens. Indent to define dependencies:

main
    feature-core
        feature-ui

C. Open PRs

Push the code and open PRs. Note: Target main for all of them to handle the fork constraint.

# 1. Base PR (Ready for Review)
git checkout feature-core
gh pr create --base main --title "Part 1: Core"

# 2. Top PR (Draft)
git checkout feature-ui
gh stack-create --title "Part 2: UI"

D. Handle Feedback (The Loop)

When a Reviewer asks for changes on feature-core:

1. Checkout feature-core, fix code, git commit --amend (or new commit).
2. Run the magic command:

   git machete traverse

   Machete automatically rebases feature-ui onto feature-core and force-pushes both.

E. Promote (After Merge)

When feature-core merges into upstream/main:

1. Sync local stack:

   git machete traverse --fetch

   Machete detects feature-core is merged and rebases feature-ui onto main.

2. Mark PR as ready:

   git checkout feature-ui
   gh stack-promote

---

Bonus: The "Oops, I committed everything to one branch" Fix

Scenario: You have 3 commits on one branch (dev) and you want to split them into 3 stacked PRs.

1. Create branches for each commit Identify the commit hashes (git log) for Commit 1, Commit 2, and Commit 3.

# Create branches pointing to specific points in history
git branch part-1 <commit-hash-1>
git branch part-2 <commit-hash-2>
git branch part-3 <commit-hash-3> # (Or just rename your current branch)

2. Organize with Machete

git machete edit

Setup the structure:

main
    part-1
        part-2
            part-3

3. Sync and Push Run the magic command to ensure the git history aligns perfectly.

git machete traverse

Machete will ask to push part-1 (Yes), then part-2 (Yes), then part-3 (Yes).

4. Create the PRs

git checkout part-1 && gh pr create --base main --title "Part 1"
git checkout part-2 && gh stack-create --title "Part 2"
git checkout part-3 && gh stack-create --title "Part 3"