git-stack/README.md

git-stack

Manage stacked branch dependencies, build preview/integration branches, and land them as clean squashed commits — in order.

Built for workflows where multiple agents (or humans) create dependent PR chains and you need to:

• Test the full stack merged together (preview builds)
• Land each branch as a single squashed commit in dependency order
• Auto-rebase downstream branches when an upstream branch lands

Install

# Copy to somewhere in your PATH
cp git-stack /usr/local/bin/
# Or just use it directly: ./git-stack

Quick Start

# In your git repo
git-stack init

# Define your stack
git-stack add fake-mode                           # depends on main (default)
git-stack add feature-A -d fake-mode              # depends on fake-mode
git-stack add feature-B -d fake-mode              # depends on fake-mode
git-stack add feature-C -d feature-A              # depends on feature-A

# See the graph
git-stack graph
# main
# ├── fake-mode
# │   ├── feature-A
# │   │   └── feature-C
# │   └── feature-B

# Check status (what's ready to land)
git-stack status

# Build a preview branch for testing/demos
git-stack preview feature-C           # merges fake-mode → feature-A → feature-C
git-stack preview --all               # merges everything
git-stack preview --all --push        # ...and push it

# Land branches (bottom-up)
git-stack land fake-mode --push       # squash-merge, rebase feature-A & feature-B
git-stack land feature-A --push       # squash-merge, rebase feature-C
git-stack land feature-B --push
git-stack land feature-C --push

Commands

Command	Description
init	Initialize .git-stack.json in the repo
add <branch> [-d deps...]	Add branch with dependencies (default: main)
remove <branch>	Remove branch from stack
status	Show stack with merge readiness
graph	Print dependency tree
preview [branch|--all]	Build integration branch for testing
land <branch>	Squash-merge into main, rebase dependents

Config

Stored in .git-stack.json at the repo root:

{
  "branches": {
    "fake-mode": ["main"],
    "feature-A": ["fake-mode"],
    "feature-B": ["fake-mode"],
    "feature-C": ["feature-A"]
  }
}

How Landing Works

1. Verifies all dependencies of the target branch are already in main
2. Squash-merges the branch into main (single commit)
3. Rebases all branches that depended on it onto new main
4. Updates .git-stack.json — removes landed branch, rewires deps to main
5. Optionally pushes main + force-pushes rebased branches (--push)

Requirements

• Python 3.8+
• Git
• No external dependencies