# 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

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

## Quick Start

```bash
# 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:

```json
{
  "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