ezstack

ezstack

Manage stacked PRs with git worktrees

A CLI tool for managing stacked pull requests using git worktrees. Create branches, sync rebases, manage PRs — all from one command line tool.

Website · Documentation · Releases

Requirements

• Git 2.20+
• fzf for interactive selection
• GitHub CLI (gh) for PR operations

Installation

Homebrew (macOS/Linux)

brew tap KulkarniKaustubh/ezstack
brew install ezstack

Go Install

go install github.com/KulkarniKaustubh/ezstack/v4/cmd/ezs@latest

From Source

git clone https://github.com/KulkarniKaustubh/ezstack.git
cd ezstack
make install

Shell Integration (Recommended)

Add to your ~/.bashrc or ~/.zshrc:

eval "$(ezs --shell-init)"

This creates a shell function that wraps the ezs binary, enabling commands like ezs goto, ezs up, and ezs new to change your shell's directory. Without shell integration, these commands will print the path and instruct you to cd manually.

Quick Start

# Configure ezstack for your repository
ezs config

# Create your first branch
ezs new feature-1

# Stack another branch on top
ezs new feature-2 --parent feature-1

# View your stack with PR and CI status
ezs status

# Create PRs
ezs pr create -t "Part 1: Add feature"

# Commit and auto-sync children
ezs commit -m "Add feature"

# Sync after changes
ezs sync -a

PR Review

Quickly check out a teammate's branch into its own worktree for review or collaboration:

# Creates a local worktree tracking the remote branch
# Registers it as a stack (root = PR base branch or main)
# Shows as (remote) in ezs ls
ezs new origin/feature-branch

# Shows PR info, review status, and line diff automatically
# You can work on it, push, sync — all commands work normally
# Fork PRs are auto-detected: adds the fork remote and pushes there
# When done, clean up with:
ezs delete feature-branch

Commands

Global flags: -y, --yes auto-confirm prompts · -h, --help · -v, --version

Run ezs <command> --help for command-specific help.

AI Agent

ezstack can launch an AI coding agent (Claude, Cursor, etc.) with full stack context injected automatically. The agent is scoped to a single stack and knows about all branches, worktree paths, and available commands. Requires worktree mode (use_worktrees: true, which is the default) — the agent needs separate working directories for each branch to operate in isolation.

# Launch agent on current stack
ezs agent

# Build a feature as stacked branches
ezs agent feature "Add user authentication with JWT tokens"

# View or edit the agent's prompt templates
ezs agent prompt --shipped work
ezs agent prompt --edit work

Agent prompts are composed from three layers: a shipped prompt (updated with releases), custom instructions (~/.ezstack/), and repo-specific instructions (<repo>/.ezstack/). See AGENTS.md for full details.

Configuration

ezstack supports both worktree-based and checkout-based workflows:

• Worktrees (default, recommended): Each branch gets its own worktree directory for parallel work. Required for ezs agent.
• No worktrees: Branches use git checkout for a simpler, single-directory workflow. All core commands (sync, commit, push, pr, reparent) work fully. Note: ezs agent is not available in this mode.

Configure with ezs config set use_worktrees true/false.

Sync Strategy

By default, ezstack uses git rebase to sync branches. You can switch to git merge per-repo:

ezs config set sync_strategy merge

Or override per-command with --merge / --rebase flags:

ezs sync -a --merge       # merge just this once
ezs commit -m "fix" --rebase  # rebase children even if config says merge

The --merge and --rebase flags work with sync, commit, amend, and reparent.

Exit Codes

Editor & Desktop Integrations

ezstack ships with first-party clients so you can drive the same ezs CLI from your editor or a native GUI:

VS Code

# Install from a pre-built VSIX (download from the Releases page)
code --install-extension ezstack-4.0.0.vsix

Then open the ezstack panel in the activity bar. Auto-refreshes on ~/.ezstack/stacks.json changes. Configure with ezstack.cliPath, ezstack.autoRefresh, and ezstack.ticketPattern.

Neovim

-- lazy.nvim
{
  "KulkarniKaustubh/ezstack",
  subdir = "neovim-plugin",
  cmd    = { "Ezs" },
  config = function() require("ezstack").setup() end,
}

Requires Neovim 0.10+ and the ezs CLI on $PATH. Run :Ezs to open the stack viewer or :Telescope ezstack branches for fuzzy picking. See :help ezstack for the full reference.

Desktop App

cd tauri-ui
npm install
npm run tauri dev      # development
npm run tauri build    # production bundle in src-tauri/target/release/bundle/

Or grab a prebuilt installer from the Releases page. Supports Remote (SSH) mode for driving ezs on a dev VM.

Documentation

See DOCUMENTATION.md for comprehensive documentation, or AGENTS.md for AI-assisted workflows.

License

MIT