Github Stacked PR

🎯 What a “Stacked PR” Is (and Why You’ll Want One) A stacked pull request (sometimes called a stacked PR, stacked diff, or dependent PR) is a series of PRs that build on top of each other, each one containing a small, logically‑isolated change. main ──► A ──► B ──► C │ │ │ │ │ └─ PR‑C (depends on B) │ └─ PR‑B (depends on A) └─ PR‑A (directly on main) A is based on main. B is based on A (its head). C is based on B, etc. When you eventually merge the stack in order (A → B → C), each change lands cleanly, and reviewers can focus on one cohesive piece at a time. Why Stack PRs? Problem Stacked PR Solution Huge, monolithic PRs that are hard to review & cause long CI times Break the work into bite‑size PRs (e.g., “feature flag”, “data model”, “UI”) Inter‑dependent changes (e.g., a new API + its consumer) Each dependent change lives in its own PR, but they still get tested together because they are built on top of each other Rebasing on main constantly drags in unrelated changes Only the bottom PR needs to be rebased onto main; the rest stay on top of it Need to ship part of a larger change early Merge the first PR in the stack; the rest stay pending until they’re ready CI resources Only the bottom PR runs the full suite against main; higher PRs can run a lighter subset because they already passed lower‑level tests 📦 The Landscape of Tools (as of 2026) Tool / Service Key Features Installation / Setup Typical Workflow ghstack (GitHub CLI plugin) - Creates stacked PRs automatically from a series of commits.- Handles base‑branch updates, resolves merge conflicts, and can re‑stack after rebases.- Works with GitHub's GraphQL API, so you get “dependent PR” links in the UI. pip install ghstack (or brew install ghstack).Requires a personal access token with repo scope. bash git checkout -b feature/stacked\n# create many commits …\nghstack push\n# later, after rebasing on main\nghstack rebase . | | GitTown (aka git-town) | - git town ship can ship a stack of dependent branches in order.- Not GitHub‑specific, works with any remote. | brew install git-town / cargo install git-town. | bash git town new featureA\n# commit …\ngit town new featureB\n# work on B …\ngit town sync | | gstack (open‑source script) | - Very lightweight Bash script that creates a series of PRs from sequential commits.- Good for CI‑only pipelines. | curl -L https://raw.githubusercontent.com/…/gstack.sh | bash. | bash gstack create . | | GitHub’s “Draft PR” + “Depends on” labels | - No external tool needed; you manually create PRs and add a depends-on: label (or a comment).- GitHub UI now shows a “This PR depends on #123” banner (rolled out in early 2026). | No install. Just enable the “Pull request dependencies” preview in your org settings. | Create PR‑A → PR‑B → PR‑C, add depends-on: #A comment on B, etc. | | pullrequest.io (SaaS) | - Managed service that visualises stacks, auto‑updates bases, and adds “stack‑status” checks.- Works with public & private repos. | Sign up, link GitHub repo, generate a machine‑user token. | UI‑driven: select commits → “Create stack”. | | Gerrit (if you’re on a hybrid workflow) | - Has native support for “dependent changes”.- Works great if you already use Gerrit for code review. | Already part of Gerrit install. | Use git review -d etc. | Bottom‑line: If you just need a quick, “no‑install” solution, the built‑in draft‑PR + depends-on label works fine. If you want to automate the entire stack lifecycle (create, rebase, update, merge), ghstack is the most mature and GitHub‑native option in 2026. 🛠️ Step‑by‑Step Guide Using ghstack (the most popular choice) Below is a complete workflow you can copy‑paste into a terminal. It assumes you have: Git 2.40+ (or newer) GitHub CLI (gh) installed and authenticated Python 3.9+ (for ghstack) 1️⃣ Install the tools # GitHub CLI (if you don’t have it) brew install gh # macOS # or: sudo apt install gh # Ubuntu # ghstack (Python package) pip install --user ghstack # make sure ~/.local/bin is on your $PATH 2️⃣ Prepare a branch and make a series of commits # Start from the latest main git checkout main git pull origin main # Create a “stack” branch (the base of the stack) git checkout -b feature/stacked # 1️⃣ First logical change (e.g., add a new API) # ------------------------------------------------- echo "def hello(): return 'world'" > hello.py git add hello.py git commit -m "feat: add hello() helper" # 2️⃣ Second logical change that depends on the first # ------------------------------------------------- cat >> hello.py