# Lattice
**Stack your prs and make yourself and your reviewers happy**
[](LICENSE)
Lattice (lt) is my take on implementing a stacked branch workflow on top of git and a git forge like github.
It's based heavily on [graphite](graphite.dev), which I think has an excellent "mental model" for stacking. If you're not familiar, the basic idea is to treat
big features (or features that depend on each other) as separate branches, and think of your "overall PR" as being made up of the composition of all of those smaller branches.
## Why Lattice?
Basically because stacking is great, and graphite is great, but the model where there's ANOTHER saas where I'm doing PR reviews (aside from github) never really clocked for me.
I've also tried a couple of other tools, like `git spr` or `git town`, but they just don't click for me.
So, I got a bunch of agents to build lattice for me. Almost 100% of this codebase has been generated by a combination of gpt pro, codex, and opus. I've specified the architecture
and overall feature set, along with test strategies and acceptance criteria.
I'm using this day-to-day, and I love it. YMMV.
**Lattice gives you:**
- Stacked branches synchronized with github PRs
- A single Rust binary (`lt`) with zero runtime dependencies
- All your code review stays in GitHub
- Metadata stored in Git itself (portable, inspectable, no external DB)
## Quick Start
```bash
# Install from crates.io
cargo install latticework
# Or build from source
cargo install --path .
# Initialize in your repo
lt init
# Authenticate with GitHub
lt auth
# Start stacking
lt create feature-auth # Create a branch
# ... make changes, commit ...
lt create feature-ui # Stack another branch on top
# ... make changes, commit ...
lt submit --stack # Push and create PRs for the whole stack
```
Your PRs will automatically include a stack visualization:
| ⬆️ | `feature-auth` | [#10](https://github.com/org/repo/pull/10) |
| 👉 | `feature-ui` | [#11](https://github.com/org/repo/pull/11) |
## Commands
### Daily Workflow
| `lt create [name]` | Create a new branch stacked on the current one |
| `lt submit` | Push branches and create/update PRs |
| `lt sync` | Fetch remote, fast-forward trunk, detect merged PRs |
| `lt log` | Display your stack with parent relationships and PR status |
### Navigation
| `lt checkout [branch]` | Switch to a tracked branch (fuzzy selection if omitted) |
| `lt up [n]` | Move up to child branch(es) |
| `lt down [n]` | Move down toward trunk |
| `lt top` | Jump to the topmost leaf of your stack |
| `lt bottom` | Jump to the lowest tracked branch above trunk |
### Stack Management
| `lt restack` | Rebase branches to align with their parents |
| `lt modify` | Amend the current commit, auto-restacking descendants |
| `lt move --onto <branch>` | Reparent a branch onto another |
| `lt squash` | Squash all commits in current branch into one |
| `lt fold` | Merge current branch into its parent |
| `lt pop` | Delete branch but keep changes as uncommitted diffs |
| `lt split` | Split a branch into multiple (by commit or by file) |
| `lt reorder` | Interactively reorder branches in your stack |
| `lt rename <name>` | Rename the current branch |
| `lt delete` | Delete a branch, re-parenting its children |
### GitHub Integration
| `lt pr [branch]` | Open PR in browser or print URL |
| `lt merge` | Merge PRs from trunk to current branch |
| `lt get <branch\|pr>` | Fetch a branch or PR from remote and track it locally |
| `lt unlink` | Remove PR linkage from metadata |
### Maintenance
| `lt doctor` | Diagnose and repair repository issues |
| `lt freeze [branch]` | Mark branch as immutable (protects against accidental changes) |
| `lt unfreeze [branch]` | Remove freeze protection |
| `lt track [branch]` | Start tracking an existing branch |
| `lt untrack [branch]` | Stop tracking a branch |
| `lt info [branch]` | Show detailed branch information |
| `lt parent` | Print current branch's parent |
| `lt children` | Print current branch's children |
| `lt continue` | Resume a paused operation after resolving conflicts |
| `lt abort` | Cancel a paused operation and rollback |
| `lt undo` | Undo the most recent Lattice operation |
### Setup
| `lt init` | Initialize Lattice in the current repo |
| `lt auth` | Store GitHub personal access token |
| `lt trunk` | Display or set the trunk branch |
| `lt config` | Manage configuration |
| `lt completion --shell <shell>` | Generate shell completions |
| `lt changelog` | Display version and release notes |
## Unique Features
### Self-Healing with `doctor`
Made changes outside of Lattice? Ran a manual `git rebase`? The `doctor` command detects inconsistencies and offers explicit repair options:
```bash
lt doctor
# Detected: Branch 'feature-x' base commit is not reachable from parent
#
# Repair options:
# [1] Restack 'feature-x' onto 'main'
# [2] Update metadata to match current state
# [3] Untrack 'feature-x'
```
Doctor never guesses. It shows you what's wrong and lets you choose how to fix it.
### Stack Comments in PRs
When you submit PRs, Lattice automatically adds a stack visualization to each PR description:
```markdown
### Stack
| ⬆️ | `feature-auth` | #10 |
| 👉 | `feature-ui` | #11 |
| ⬇️ | `feature-tests` | #12 |
```
Reviewers instantly see where each PR fits in the larger change. The table updates automatically when you re-submit.
### Freeze Protection
Working with a teammate's branch? Freeze it to prevent accidental modifications:
```bash
lt get 123 # Fetch PR #123 (frozen by default)
lt freeze feature-shared # Or freeze any branch explicitly
```
Frozen branches block rebases, amends, and other rewrites until you explicitly unfreeze them.
### Empty Branch Support
Plan your stack before writing code:
```bash
lt create step-1 # No commits yet, just a placeholder
lt create step-2 # Stack another placeholder
lt create step-3 # And another
lt down 2 # Go back to step-1 and start coding
```
## Configuration
Lattice uses a layered configuration system:
1. **CLI flags** (highest priority)
2. **Repo config** (`.git/lattice/repo.toml`)
3. **Global config** (`~/.lattice/config.toml`)
Common settings:
```bash
lt config set trunk main # Set default trunk branch
lt config set submit.draft true # Create PRs as drafts by default
lt config list # See all settings
```
## Global Flags
These flags work with any command:
| `--help, -h` | Show help |
| `--version` | Show version |
| `--quiet, -q` | Minimal output |
| `--debug` | Verbose logging |
| `--cwd <path>` | Run as if in that directory |
| `--interactive / --no-interactive` | Control prompts |
## Also notable
- Graphite
- Git town
- Git spr
## Contributions
Have a feature you want to see or implement? Please do! Open PRs to your hearts content.
## License
MIT