Stacked Diffs

Your PR is 2,000 lines. Your reviewer’s eyes glaze over. “LGTM” with no real review. Stacked diffs fix this. Break one big feature into a stack of small, reviewable PRs:

PR #3: Add login UI          (200 lines, depends on #2)
   │
PR #2: Add auth API          (300 lines, depends on #1)
   │
PR #1: Add User model        (150 lines)

Each PR is small enough to actually review. wit manages the dependencies so you don’t have to.

Quick Start

# Start a new stack from main
wit stack create auth-feature

# Create first branch and make changes
wit stack push
wit add . && wit commit -m "Add login form"

# Create next branch building on the first
wit stack push
wit add . && wit commit -m "Add logout functionality"

# See the entire stack
wit stack show

# Sync all branches after main updates
wit stack sync

# Submit all branches for review
wit stack submit

Commands

`wit stack create`

Start a new stack from the current branch.

wit stack create <name> [-d <description>]

Option	Description
`-d <desc>`	Optional description for the stack

Examples:

wit stack create auth-feature
wit stack create auth-feature -d "User authentication flow"

After creating a stack, you’ll see:

✓ Created stack 'auth-feature'
  Base branch: main
  
Next steps:
  wit stack push     # Create first branch in stack
  wit commit -m "..." # Make your changes
  wit stack push     # Create next branch

`wit stack push`

Create a new branch on top of the stack.

wit stack push [branch-name]

If no branch name is provided, wit automatically generates one based on the stack name (e.g., auth-feature/part-1, auth-feature/part-2). Examples:

wit stack push                    # Auto-named branch
wit stack push login-component    # Custom name

`wit stack pop`

Remove the top branch from the stack (keeps the branch itself).

wit stack pop

This removes the branch from stack tracking but doesn’t delete the Git branch.

`wit stack list`

Show all stacks in the repository.

wit stack list

Output:

Stacks:

* auth-feature
    Base: main
    Branches: 3
    User authentication flow

  api-refactor
    Base: main
    Branches: 2

The * indicates the current active stack.

`wit stack show`

Show a visualization of the current stack or a specific stack.

wit stack show [stack-name]

Output:

Stack: auth-feature

✓ auth-feature/part-3 ✓
  abc1234 Add password reset

  │
✓ auth-feature/part-2 ⬆3
  def5678 Add logout functionality

  │
  auth-feature/part-1 ✓
  ghi9012 Add login form

Legend: ✓ synced | ⬇ behind | ⬆ ahead | ⚠ diverged

`wit stack sync`

Rebase the entire stack when the base branch changes.

wit stack sync

This command:

Fetches the latest base branch
Rebases each branch in order from bottom to top
Reports any conflicts that need resolution

Handling Conflicts:

✗ Sync failed
  Conflicts in:
    auth-feature/part-2
      - src/auth/login.ts

Resolve conflicts and run:
  wit rebase --continue
  wit stack sync

`wit stack submit`

Push all stack branches to the remote for review.

wit stack submit [--force]

Option	Description
`--force, -f`	Force push all branches

This prepares all branches for review by ensuring they’re pushed to the remote.

`wit stack delete`

Delete a stack (keeps the branches).

wit stack delete <name>

Example:

wit stack delete auth-feature

Output:

✓ Deleted stack 'auth-feature'

The following branches still exist:
  auth-feature/part-1
  auth-feature/part-2
  auth-feature/part-3

Use "wit branch -d <name>" to delete them

`wit stack up`

Move to the child branch (one level up in the stack).

wit stack up

`wit stack down`

Move to the parent branch (one level down in the stack).

wit stack down

`wit stack goto`

Jump to a specific branch in the stack by name or index.

wit stack goto <branch|index>

Examples:

wit stack goto 2                    # Go to branch at position 2
wit stack goto auth-feature/part-3  # Go to specific branch

Advanced Operations

`wit stack reorder`

Reorder branches in the stack.

wit stack reorder <branch1> <branch2> ...

Example:

wit stack reorder feature/part-2 feature/part-1 feature/part-3

After reordering, run wit stack sync to rebase branches to the new order.

Workflow Example

Here’s a complete workflow for implementing a user authentication feature:

# 1. Start on main and create a stack
wit checkout main
wit pull
wit stack create user-auth -d "Complete user authentication system"

# 2. First PR: Data models
wit stack push data-models
# ... make changes ...
wit add . && wit commit -m "Add User model and migrations"

# 3. Second PR: API endpoints (depends on models)
wit stack push api-endpoints
# ... make changes ...
wit add . && wit commit -m "Add auth API endpoints"

# 4. Third PR: Frontend (depends on API)
wit stack push frontend
# ... make changes ...
wit add . && wit commit -m "Add login/logout UI components"

# 5. View the stack
wit stack show
# Stack: user-auth
#
# ✓ frontend ✓
#   │
# ✓ api-endpoints ✓
#   │
#   data-models ✓

# 6. Main was updated - sync the stack
wit stack sync

# 7. Submit all for review
wit stack submit

# 8. Navigate between branches for updates
wit stack goto data-models
# ... make review fixes ...
wit amend
wit stack sync    # Propagate changes up the stack
wit stack submit

Best Practices

Keep Branches Small

Each branch in a stack should represent a single logical change. Aim for:

200-400 lines of code changes
One clear purpose per branch
Easy to review in isolation

Order by Dependency

Structure your stack so each branch builds on the previous:

Data models / types first
Backend logic second
Frontend / UI last

Sync Frequently

Run wit stack sync after:

Pulling updates to base branch
Making changes to lower branches
Before submitting for review

Communicate Stack Structure

When creating PRs, mention that they’re part of a stack:

## Stack
This PR is part of a stack:
- #101 Add User model (this PR)
- #102 Add auth API endpoints (depends on this)
- #103 Add login UI (depends on #102)

Troubleshooting

Conflict During Sync

If you encounter conflicts during wit stack sync:

Resolve conflicts in the current branch
Run wit rebase --continue
Run wit stack sync to continue syncing remaining branches

Branch Not in Stack

If you get “Not currently on a stacked branch”:

wit stack list              # See available stacks
wit stack show <stack-name> # See branches in a stack
wit checkout <branch>       # Switch to a stack branch

Recovering from Failed Sync

If sync fails partway through:

wit rebase --abort          # Abort current rebase
wit stack show              # See stack state
wit checkout <branch>       # Go to the branch that failed
# Fix the issue
wit stack sync              # Try again

Get Started

Commands

Visual Interfaces

AI & Intelligence

Workflows

GitHub & Team

Advanced

Configuration

Platform

Architecture

Database

Stacked Diffs

Quick Start

Commands

`wit stack create`

`wit stack push`

`wit stack pop`

`wit stack list`

`wit stack show`

`wit stack sync`

`wit stack submit`

`wit stack delete`

Navigation

`wit stack up`

`wit stack down`

`wit stack goto`

Advanced Operations

`wit stack reorder`

Workflow Example

Best Practices

Keep Branches Small

Order by Dependency

Sync Frequently

Communicate Stack Structure

Troubleshooting

Conflict During Sync

Branch Not in Stack

Recovering from Failed Sync

​Quick Start

​Commands

​wit stack create

​wit stack push

​wit stack pop

​wit stack list

​wit stack show

​wit stack sync

​wit stack submit

​wit stack delete

​Navigation

​wit stack up

​wit stack down

​wit stack goto

​Advanced Operations

​wit stack reorder

​Workflow Example

​Best Practices

​Keep Branches Small

​Order by Dependency

​Sync Frequently

​Communicate Stack Structure

​Troubleshooting

​Conflict During Sync

​Branch Not in Stack

​Recovering from Failed Sync

Quick Start

Commands

`wit stack create`

`wit stack push`

`wit stack pop`

`wit stack list`

`wit stack show`

`wit stack sync`

`wit stack submit`

`wit stack delete`

Navigation

`wit stack up`

`wit stack down`

`wit stack goto`

Advanced Operations

`wit stack reorder`

Workflow Example

Best Practices

Keep Branches Small

Order by Dependency

Sync Frequently

Communicate Stack Structure

Troubleshooting

Conflict During Sync

Branch Not in Stack

Recovering from Failed Sync