Skip to content

Stack health

Commands to validate, repair, and test your stack metadata.

st stats

Single-screen, local-only snapshot of stacking health: stack shape, PR mix, restack/parent/dirty health, worktree lanes, local branch hygiene, and a next-action hint. Read-only and safe to run at any time.

st stats              # all tracked branches
st stats --current    # scope to the current stack only
st stats --json        # machine-readable output
st stats --ci           # add an opt-in CI roll-up (network call, reuses the standup CI pattern)
  • Stack shape — tracked branch count, number of independent stacks, deepest stack, and average stack height.
  • PR mix — open/draft/ready/no-PR/frozen counts across the scoped branches.
  • Health — branches needing restack, branches with missing parent metadata, and (repo-wide, not scoped by --current) dirty linked worktrees.
  • Worktrees — linked worktree count and idle pool slots.
  • Attention — up to a few highlighted items: stacks needing restack, branches without a PR, branches with missing parent metadata, and dirty/clean worktree lanes.
  • Biggest stacks — the largest (by height) independent stacks, with commits-ahead and PR range. Shown only when there are at least two stacks to compare.
  • PR mix chart — a bar chart of ready/draft/no-PR, shown only when at least two of those categories are non-zero.
  • Hygiene — merged-but-local, upstream-gone, and stale branch counts (same classification as st sweep), with a hint to run st sweep --delete.
  • Next — one or two suggested follow-up commands (e.g. st restack --all then st ss, or st sweep).

Counters with a zero value are omitted rather than printed as 0, and the health row collapses to ✓ all clear when nothing needs attention.

--ci is opt-in because it makes a network call; without it (or without forge auth configured), the CI line is omitted and st stats still exits 0.

st validate

Check that all branch metadata is consistent.

st validate

Runs:

  • Orphaned metadata — metadata refs for deleted branches
  • Missing parents — metadata points to a parent that no longer exists
  • Cycle detection — loops in the parent chain
  • Invalid metadata — unparseable JSON
  • Stale parent revision — parent has moved since last restack

Exit code 0 if healthy, 1 if issues found.

Validation and other read commands never delete metadata. Orphaned refs remain available for inspection until an explicit st fix removes them.

st doctor --fix

Check repo/config health, print a repair plan, and apply safe local repairs after one confirmation.

st doctor --fix

Repairs in this mode are intentionally conservative:

  • Sets recommended global Git config (rerere.enabled=true, rebase.autoStash=true) when missing.
  • Updates already-installed stale AI agent skill files.

It does not mutate branch refs, PR metadata, remotes, or worktree contents.

st fix

Auto-repair broken metadata. Wrapped in a transaction so st undo works.

st fix            # interactive repair
st fix --yes      # auto-approve all fixes
st fix --dry-run  # preview without changing anything

Repairs:

  • Deletes orphaned metadata
  • Reparents orphaned branches to trunk when the parent is gone
  • Deletes invalid metadata
  • Reports branches that need restack

Restack preflight repair

Before rebasing each branch, st restack, st upstack restack, and st rs --restack compare the stored parentBranchRevision against merge-base(parent, branch). When the stored boundary would force git to replay a much larger range than the merge-base, stax automatically uses the merge-base as the rebase boundary for that operation and prints a non-fatal notice:

  preflight: 'feature-x' stored boundary would replay 312 commit(s); using merge-base boundary (2 commit(s)).
    Stax will rebase 'feature-x' with the merge-base boundary to avoid replaying unrelated history from 'main'.

This usually means metadata drifted (e.g. branch tracked late) or git merge main was run on the branch instead of restack — both can produce conflicts on files you never edited. The repair happens automatically; after a successful restack, metadata is refreshed to the current parent tip as usual.

Silence the notice with [restack] preflight_warn = false in ~/.config/stax/config.toml or with --quiet. Disable the automatic correction with [restack] preflight_auto_repair = false.

st run <cmd> (alias: st test <cmd>)

Run a shell command on each branch in the stack, bottom to top (excluding trunk), returning to the starting branch afterward.

st run "cargo test"                    # current stack
st run --stack "make test"             # explicit current stack
st run --stack=feature-a "make test"   # a specific stack
st run --all "true"                    # all tracked branches
st run --fail-fast "cargo check"       # stop on first failure
Flag Behavior
--fail-fast Stop after the first failing branch
--all Run on all tracked branches
--stack[=<branch>] Run one stack (current by default)

Example output:

Running 'cargo test' on 3 branch(es)...

  feature-a:   SUCCESS
  feature-b:   FAIL
  feature-c:   SUCCESS

2 succeeded, 1 failed
Failed branches:
  feature-b

Exit code 1 if any branch fails.

If a restack stops on a conflict, both executable names (st and stax) return exit code 2; the conflict details are printed once before control returns to the shell.