Submitting stacked diffs to GitHub as separate pull requests can be cumbersome. ghstack addresses this by providing a command-line interface to streamline the process, enabling developers to manage and submit series of dependent commits efficiently as individual PRs, facilitating easier code review and integration.

How It Works

ghstack manages stacked Git commits by pushing each commit as a separate GitHub Pull Request. It creates three internal branches per PR: base (original commit's base), head (the commit itself on top of base), and orig (the local commit). PRs target merging head into base, enabling granular review of individual changes within a stack. It also integrates with LLMs (Claude, Codex) for automated PR description summarization.

Quick Start & Requirements

• Install: uv tool install ghstack or pip install ghstack.
• Prerequisites: Python 3.9.1 or higher. A GitHub Personal Access Token with public_repo scope is required.
• Configuration: Set up ~/.ghstackrc with github_url, github_oauth, github_username, and optional remote_name and automsg.
• Usage: Prepare commits on top of main, then run ghstack.

Highlighted Details

• Automated PR context generation using LLMs (Claude/Codex) based on commit messages and diffs.
• Dedicated ghstack land command required for merging PRs, as standard GitHub UI merging is not supported.
• Internal branch structure (gh/username/N/base, gh/username/N/head, gh/username/N/orig) facilitates PR creation and tracking.
• Supports rebasing (git rebase origin/main) over merging for stack updates.

Limitations & Caveats

Commits managed by ghstack cannot be merged via the standard GitHub UI due to their non-main branch bases; the ghstack land command is mandatory. Users must implement a separate mechanism for pruning stale branches pushed to the upstream repository. Rebasing is required over merging, with conflicts needing resolution on a per-PR basis.