gh-stack: manage stacked PRs with GitHub CLI

Who it's for

gh-stack is a GitHub CLI extension for managing stacked branches and Pull Requests. It fits people already using GitHub CLI who need to move a sequenced set of branches as one stack. The summary also says installing the extension requires GitHub CLI v2.0+.

The material mentions you can install the gh-stack skill so an AI coding agent understands stacked PRs and the gh stack command line; the excerpt only says "install that skill" and does not give a second install command, so do not invent an installer that never appears. The material does not list agent products; do not treat this as a feature exclusive to one editor. The official guide page is

https://github.com/github/gh-stack

First try in 3 minutes

The official install command is this one from the excerpt:

gh extension install github/gh-stack

Prerequisite: GitHub CLI is already on this machine, and the version meets the v2.0+ called out in the summary. This command writes an extension onto the machine, so it has side effects. Confirm the current repository and account are the environment you want to try the stack in, then run the install.

Low-risk check after install: do not create a branch immediately. First confirm the gh stack command is already findable by the CLI. The material explains gh stack init as "start a new stack, and create and check out the first branch"; that changes the workspace, so get confirmation before running:

gh stack init

Success signal: after install, gh recognizes the stack subcommand. If you confirmed you want a new stack, after init the current repository has the new first branch, and you can later see JSON metadata in the uncommitted .git/gh-stack. If you only want to read the guide first, stop after a successful install and do not init.

Use cases

Case 1: Start a new stacked branch. In a repository where the extension is installed, confirm you may change branches, then run gh stack init. The material writes this as creating and checking out the first branch. The summary also mentions adding layers, pushing, viewing, then opening a set of PRs later, but the excerpt does not give complete spellings of those later subcommands, so this case is done only when "the first branch is created and checked out"; do not write push or opening a PR as already copy-pasteable steps.

Case 2: Check where stack metadata lands, so you know what to look at after an interrupted rebase. The material states: stack metadata lives in .git/gh-stack, a JSON file that is not committed into the repository, recording which branches belong to which stack and in what order; interrupted rebase state is stored separately in .git/gh-stack-rebase-state. This is a read-only check: open those two paths, confirm the files exist, and confirm the JSON is tracking the current branch order. Do not hand-edit these files unless the same page gives other steps; the excerpt does not give an edit format.

Boundaries

The extension only covers managing stacked branches and Pull Requests. Metadata is in .git/gh-stack and does not enter the versioned tree; interrupted rebase state is in .git/gh-stack-rebase-state. init creates and checks out a branch; it is not a read-only command.

Do not invent a skill install command that never appears in the excerpt, and do not treat adding layers, pushing, viewing, or submitting from the summary as an already given subcommand list. The material does not name clients, and does not say how to use this outside GitHub CLI. Beyond these written install, init, and metadata locations, this guide does not cover the rest.