giff stack documentation

giff stack is an open-source tool for stacked-diff workflows on GitHub. This is the complete reference: concepts, commands, install, contribution, and an honest section on what it doesn't do.

What you'll find here

Installation — get the CLI, the web dashboard, and the runner up and running.
Concepts & first principles — frames, stacks, the one-commit-per-frame rule, trees vs linear.
Commands — every CLI command with before/after diagrams.
Why we made this — the motivation and the design choices.
Limitations — who shouldn't use this, and why.
Contributing — the codebase structure, build, and PR process.

Three components

giff stack has three pieces. They're independently useful — install only what you need.

flowchart TB
  cli["<b>giff CLI</b><br/><span style='color:#86868b;font-size:12px'>Rust · stack management on your machine</span>"]
  web["<b>giff web</b><br/><span style='color:#86868b;font-size:12px'>SvelteKit · read-only dashboard</span>"]
  runner["<b>giff-runner</b><br/><span style='color:#86868b;font-size:12px'>Rust + SQLite · webhooks, polling, auto-merge</span>"]
  github(["<b>GitHub API</b><br/><span style='color:#86868b;font-size:12px'>source of truth</span>"]):::brand
  cli --> github
  web --> github
  runner --> github
  classDef brand fill:#ff0035,stroke:#ff0035,color:#ffffff;

Three components. CLI is mandatory; web and runner are optional adds.

The 30-second tour

bash

# 1. Install (the crate is named giffstack; the binary it ships is giff)
cargo install giffstack

# 2. Configure
giff init
export GITHUB_TOKEN=ghp_xxx   # or paste into ~/.config/giff/config.toml

# 3. Make a stack
git add .
giff publish "feat: scaffold auth"     # frame 1: branch + commit + register
git add .
giff publish "feat: add token signing" # frame 2 stacks on top
giff push                              # opens both PRs

# 4. Inspect
giff log                               # tree view
giff status                            # where am I

# 5. After a review approves the bottom PR
giff sync                              # rebases the rest
giff stack land                        # merges PR #1, retargets PR #2 to main