About this project

gh stack is a GitHub CLI extension that manages stacked branches and pull requests. Stacked PRs split a large change into a chain of small, reviewable pull requests that build on each other; this tool automates branch creation, keeping branches rebased, setting correct PR base branches, and navigating between layers. Installation is via `gh extension install github/gh-stack` and requires GitHub CLI v2.0+. An optional skill can be installed for AI coding agents. Core model: a stack is an ordered list of branches, each based on the one below it, with the bottom based on a trunk branch (typically main). Stack metadata is stored locally in `.git/gh-stack` as JSON, with rebase state in a separate file. Commands include: - init: initialize a stack, optionally adopting existing branches, with a configurable trunk. - add: create a new branch on top of the stack, with options to stage and commit changes. - checkout: check out a stack by stack number, PR number, PR URL, or branch name, including an interactive picker for local and remote stacks. - rebase: fetch and cascade rebases across the stack, with downstack/upstack/no-trunk scoping and continue/abort handling. - modify: an interactive terminal UI to drop, fold, insert, rename, and reorder branches. - sync: fetch, reconcile remote stack, fast-forward trunk, cascade rebase, push, sync PR state, link the stack, and optionally prune merged branches. - push: push active branches with per-branch force-with-lease checks. - submit: push branches and create or update PRs and the GitHub stack, with an interactive editor or auto mode. - link: create or update a GitHub stack from branch names or PR numbers without local tracking, useful with other local branch tools. - merge: merge one or more stacked PRs in an all-or-nothing operation, with merge-method options and merge-queue awareness. - view: display stack branches, ordering, PR links, and recent commits, with short and JSON output. - unstack/delete: remove a stack from local tracking and/or GitHub. - Navigation commands (up, down, top, bottom) move between branches in the current stack. The README documents flags, examples, preconditions, and behaviors such as divergence handling and merge-queue interactions in detail.