gitbutler-stacks

# GitButler Stacks

Dependent branches → anchor-based stacking → reviewable chunks.

<when_to_use>

- Sequential dependencies (e.g., refactor → API → frontend)
- Large features broken into reviewable chunks
- Granular code review (approve/merge early phases independently)
- Post-hoc stack organization after exploratory coding

NOT for: independent parallel features (use virtual branches), projects using Graphite stacking

</when_to_use>

## Stacked vs Virtual Branches

| Type | Use Case | Dependencies |
|------|----------|--------------|
| **Virtual** | Independent, unrelated work | None — parallel |
| **Stacked** | Sequential dependencies | Each builds on parent |

Stacked branches = virtual branches split into dependent sequence.
Default: Virtual branches are stacks of one.

## Creating Stacks

```bash
# Base branch (no anchor)
but branch new base-feature

# Stacked branch (--anchor specifies parent)
but branch new child-feature --anchor base-feature

# Third level
but branch new grandchild-feature --anchor child-feature
```

**Result:** `base-feature` ← `child-feature` ← `grandchild-feature`

**Short form:** `-a` instead of `--anchor`

```bash
but branch new child -a parent
```

## Stack Patterns

Common patterns: feature dependency chains, refactoring sequences, deep stacks.

**Example - Feature Dependency:**

```bash
but branch new auth-core
but branch new auth-oauth --anchor auth-core
but branch new auth-social --anchor auth-oauth
```

See `references/patterns.md` for detailed patterns with commit examples.

## Post-Hoc Stack Organization

Convert independent branches into a stack by recreating with correct anchors:

1. Create new branch with `--anchor` pointing to intended parent
2. Move commits with `but rub <sha> <new-branch>`
3. Delete original branch

See `references/reorganization.md` for detailed workflows.

## Publishing Stacks

### Using `but publish` (Preferred)

```bash
# Publish entire stack - pushes and creates PRs
but publish

# Publish specific