Deprecated: This module has moved to github.com/KulkarniKaustubh/ezstack/v4.
The highest tagged major version is
README
¶
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.
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/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
Commands
| Command | Aliases | Description |
|---|---|---|
new |
n |
Create a new branch in the stack |
list |
ls |
List all stacks and branches |
status |
st |
Show status with PR and CI info |
sync |
rebase, rb |
Sync stack with remote (rebase or merge) |
goto |
go |
Navigate to a branch worktree |
up |
Navigate up the stack (toward parent) | |
down |
Navigate down the stack (toward children) | |
reparent |
rp |
Change the parent of a branch |
stack |
Add a branch to a stack | |
unstack |
Remove a branch from tracking | |
delete |
del, rm |
Delete a branch and its worktree |
commit |
ci |
Commit and auto-sync child branches |
amend |
Amend last commit and auto-sync children | |
push |
Push current branch or entire stack | |
diff |
Show diff against parent branch | |
pr |
Manage pull requests (create, update, merge, draft, stack) | |
config |
cfg |
Configure ezstack |
menu |
Interactive command menu |
Global flags: -y, --yes auto-confirm prompts · -h, --help · -v, --version
Run ezs <command> --help for command-specific help.
Configuration
ezstack supports both worktree-based and checkout-based workflows:
- Worktrees (default): Each branch gets its own worktree directory for parallel work
- No worktrees: Branches use
git checkoutfor a simpler, single-directory workflow
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
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | General error |
| 2 | Usage/argument error |
| 3 | Rebase conflict |
| 4 | Not in a git repository |
| 5 | Not in a stack |
| 6 | GitHub authentication required |
| 7 | Branch not found |
| 8 | Network/remote error |
| 10 | User cancelled |
Documentation
See DOCUMENTATION.md for comprehensive documentation, or AGENTS.md for AI-assisted workflows.
License
MIT
Directories