Maintenance

Health checks, cleanup, and safe merge commands — doctor, ready, prune, merge-check, merge-next, land, and post-merge.

dub doctor

Run health checks for stack metadata and submit readiness:

dub doctor

# Check all stacks
dub doctor --all

# Skip remote fetch
dub doctor --no-fetch

Checks include:

in-progress operation detection
missing tracked branches
submit blockers
local/remote SHA drift
structural parent/child ancestry drift, where a child branch is no longer based on its tracked parent even if local and remote refs match
remote GitHub base drift, where the remote PR head is no longer descended from the base branch GitHub is actually evaluating

If dub doctor reports that a branch is no longer based on its parent, start with:

dub restack
dub doctor

If the stack looks healthy after restacking and you still need to refresh the PR from your current branch, follow with:

dub submit

If dub doctor reports that a branch is not based on its GitHub base, refresh that base first, then replay and resubmit the branch:

git checkout main && git pull --ff-only origin main
dub restack
dub submit

dub ready

Run pre-submit checklist (doctor + submit preflight):

# Default: current branch + ancestors (downstack)
dub ready

# Just the current branch
dub ready --scope current

# Every branch in the stack (siblings included)
dub ready --scope stack

dub prune

Preview or remove stale tracked branch metadata:

# Preview only
dub prune

# Apply removals
dub prune --apply

# Include every stack
dub prune --all --apply

dub merge-check

Validate merge order and GitHub mergeability for a stack PR:

# Check current branch PR (scope: current, default)
dub merge-check

# Check current branch + ancestors
dub merge-check --scope downstack

# Check every branch in the stack (siblings included)
dub merge-check --scope stack

# Check an explicit PR number (scope ignored)
dub merge-check --pr 123

Merge the next safe PR in your current stack path. Direct merges pre-retarget direct child PRs and run post-merge maintenance; GitHub merge-queue branches enqueue the PR and wait for a later dub sync:

dub merge-next
# alias
dub land

# Preview only
dub merge-next --dry-run

# Require queue mode
dub merge-next --queue

dub post-merge

Repair stack metadata and retarget remaining PRs after manual merges:

dub post-merge

# Preview only
dub post-merge --dry-run

# Include all stacks
dub post-merge --all

Stale Branch Recovery

When submit or sync gets blocked by stale tracked branches:

# 1) Inspect current health
dub doctor

# 2) Preview stale branch metadata
dub prune

# 3) Remove stale metadata if confirmed
dub prune --apply

# 4) Re-run pre-submit checks
dub ready

# 5) Submit current linear path
dub submit

Hidden Conflict Recovery

If GitHub shows a stacked child PR as conflicting but your local branch looks clean:

# 1) Surface structural drift locally
dub doctor

# 2) Replay children onto their tracked parents
dub restack

# 3) Re-check health before pushing
dub doctor

# 4) Refresh the current PR path if needed
dub submit

# 5) Confirm GitHub now sees the PR as mergeable
dub merge-check