ghstack

What it is and what it does

ghstack is a command-line tool that transforms a linear stack of local Git commits into a series of interdependent pull requests on GitHub. Instead of manually creating and managing multiple PRs that depend on each other, you prepare commits sequentially on a branch and run ghstack once; it pushes each commit as a separate PR with synthetic base and head branches, automatically tracking interdiffs on subsequent runs. This workflow is particularly useful for large features or refactorings that are easier to review in logical chunks but need to land as a coherent stack.

The tool manages three branches per commit (base, head, and orig), handles rebasing and modification of commits in the stack, and provides a `ghstack land` command to merge stacked PRs in the correct order. It integrates with GitHub's API via a personal access token and supports optional AI-powered commit message generation via Claude or Codex. The package is actively maintained, has low installation friction, and carries no known security vulnerabilities.

Use it for:

• Land a large refactoring as a series of logically independent but stacked PRs for easier review.
• Update an existing stacked PR by editing the commit and running ghstack again to push the interdiff.
• Rebase a local commit stack against the upstream main branch while preserving ghstack PR metadata.
• Automate PR description generation using Claude or Codex when pushing stack updates.
• Merge a completed stack of PRs in dependency order using ghstack land instead of GitHub's UI.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

ghstack submits stacks of local Git commits to GitHub as separate pull requests, each with its own branch structure and automatic interdiff tracking.

Yes, if you regularly work with feature branches that benefit from logical subdivision into reviewable chunks and want to avoid manual PR choreography. The tool is actively maintained, has no known vulnerabilities, and low install friction. Not necessary for simple single-commit workflows or teams that prefer squash-and-merge strategies.

Install

ghstack on PyPI

pip install ghstack

uv add ghstack

poetry add ghstack

Installing ghstack

Before you install

Low install friction with a pure Python wheel. Active maintenance with a recent release (16 days old) and steady repository activity. Requires Python 3.9.1 or later.

License in practice

MIT license permits free use, modification, and distribution with minimal restrictions—suitable for both personal and commercial projects.

Quickstart

pip install ghstack

# Configure with GitHub token
echo '[ghstack]\ngithub_oauth = your_token\ngithub_username = your_username' > ~/.ghstackrc

# Create commits on a branch, then:
ghstack

Requires Python 3.9.1 or later. Needs a GitHub personal access token with public_repo scope and write permission to the target repository.

Verify before relying

• Whether the aiohttp, requests, click, and flake8 dependencies are all required at runtime or if some are optional/development-only.
• Whether the tool works with GitHub Enterprise or only github.com.
• Performance characteristics when working with very large stacks (number of commits).

Package facts

Evidence: ghstack-0.17.0-py3-none-any.whl

Tags

More Software Development packages