Split large changes into small, sequential review units
Instead of changing hundreds of lines at once, organizing code so that each layer builds on the one below makes it easier for reviewers to understand at a glance. This tool automates the tedious work of creating and maintaining that structure. It handles creating branches, updating them to the latest state, and setting the correct base branch with a single command.
Stack structure and how it works
A stack is an ordered list of branches, where each branch is based on the one directly below it. The bottom branch connects to a trunk like the main branch, and newer changes accumulate as you move up. When a reviewer opens a PR for a specific branch, they see only the diff for that layer, which increases focus. gh stack records this hierarchy locally and integrates with GitHub's stack feature to manage PRs as a single group.
Daily workflow
In particular, gh stack sync fetches remote changes, rebases, and synchronizes PR status in one go. If conflicts occur during this process, the operation pauses, and you can resume it after resolving them using --continue.
Branch reorganization and worktree support
All changes are verified in a preview step and applied all at once when saved. It also supports Git worktrees, allowing you to manage multiple stacks independently or distribute the branches of a single stack across multiple worktrees. During rebasing or synchronization, it automatically finds and updates the worktree owning each branch, leaving other worktrees untouched.
Things to check before adoption
This tool requires GitHub CLI v2.0 or higher and Git 2.36 or higher. After installation, update notifications are cached for 24 hours and can be disabled via an environment variable if desired. To use it with AI coding agents, you must install a separate skill. Local metadata is stored in .git/gh-stack and is shared between worktrees. When upgrading versions, it is recommended to complete or abort existing tasks to maintain compatibility with previous versions. In complex worktree environments, changes are serialized, so it is safer not to run them concurrently with other Git commands.
