Skip to main content
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>]
OptionDescription
-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:
  1. Fetches the latest base branch
  2. Rebases each branch in order from bottom to top
  3. 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]
OptionDescription
--force, -fForce 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:
  1. Data models / types first
  2. Backend logic second
  3. 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:
  1. Resolve conflicts in the current branch
  2. Run wit rebase --continue
  3. 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