Bertram Gilfoyle
71bb30eec8
Manage dependent branch chains with: - Dependency graph tracking (.git-stack.json) - Preview/integration branch builds for testing - Ordered squash-merge landing with automatic rebase cascade - Visual dependency graph display
92 lines
2.7 KiB
Markdown
92 lines
2.7 KiB
Markdown
# 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
|