stackinator

README

Stackinator

A minimal CLI tool for managing stacked branches and syncing them to GitHub Pull Requests, inspired by tools like Charcoal and Graphite.

Features

• 🪜 Stack Management: Create and manage chains of dependent branches
• 🔄 One-Command Sync: Rebase all branches, push changes, and update PR bases automatically
• 📊 Visual Status: See your stack structure at a glance
• 🎯 Minimal State: Uses git config to track parent relationships - no extra files or databases
• 🔧 Simple Integration: Works with standard git and GitHub CLI (gh)

Installation

Prerequisites

• Git
• GitHub CLI (gh)

Homebrew (macOS/Linux)

brew install javoire/tap/stackinator

See Alternative Installation Methods for other options (Go install, binary download, build from source).

Quick Start

1. Create a Stack

Start from your base branch (e.g., main):

# Create first branch in stack
stack new feature-1

# Make some changes and commit
git add .
git commit -m "Add feature 1"

# Create second branch stacked on feature-1
stack new feature-2

# Make more changes
git add .
git commit -m "Add feature 2"

2. View Your Stack

stack status

○ main
│
○ feature-1 [https://github.com/you/repo/pull/1 :open]
│
● feature-2 [https://github.com/you/repo/pull/2 :open]

The ● indicates your current branch.

3. Sync Everything

After making changes or when the base branch is updated:

stack sync

This will:

• Fetch latest changes from origin
• Rebase each branch onto its parent (in order)
• Force (with lease) push all branches
• Update PR base branches to match the stack
• Handle merged parent PRs automatically

Commands

See Commands Reference for full documentation.

• stack new <branch-name> - Create a new branch in the stack
• stack status - Display the current stack structure
• stack sync - Sync all branches and update PRs
• stack parent - Show the parent of the current branch
• stack prune - Clean up branches with merged PRs
• stack rename <new-name> - Rename branch preserving stack relationships
• stack parent <new-parent> - Change the parent of the current branch
• stack worktree <branch-name> - Create a worktree for a branch

Configuration

Configure the base branch and worktrees directory with git config:

git config stack.baseBranch develop  # Default is "main"
git config stack.worktreesDir ~/worktrees

Or use the interactive helper:

stack config set

AI Coding Tools

Stackinator includes a skill that teaches AI coding tools how to manage stacked branches. Supported tools: Claude Code, Codex, and Cursor.

stack skill install

This auto-detects which tools are installed and installs the skill for all of them.

Manual install

For Claude Code, run:

/plugin marketplace add javoire/stackinator
/plugin install stack@stackinator

For Codex, run:

codex plugin marketplace add javoire/stackinator
codex plugin add stack@stackinator

Documentation

• How It Works - Stack tracking and sync algorithm
• Configuration - Customizing Stackinator
• Examples - Workflow examples and tips
• Troubleshooting - Common issues and solutions

License

MIT

Contributing

Contributions welcome! See Contributing Guide for development setup and guidelines.

Acknowledgments

Inspired by:

• Charcoal
• Graphite
• git-stack