---
id: ghstack
version: "0.17.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# ghstack — Stack diff support for GitHub

License: permissive · Maintenance: active · Downloads: 169.9K/mo

## 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 above — 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

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

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 169.9K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

stack pull requests github, git commit stack automation, github stacked diffs, multi-commit pr workflow, dependent pull requests, git-workflow, github-automation

[View on SkillFed](https://skillfed.io/packages/ghstack) · [View on PyPI](https://pypi.org/project/ghstack/)