3.3 KiB

Raw Blame History

Stack Recovery Procedures

When parallel agents or mixed git/gt operations corrupt the stack.

Symptoms of Corruption

Branches appear as siblings instead of parent-child
PRs contain files from wrong features
PR titles don't match branch content
gt status shows unexpected structure
gt ls shows flat tree instead of stack

Recovery Workflow

Assess → Save Work → Fix Relationships → Redistribute → Restack → Submit

Phase 1: Assess Damage

# Save uncommitted work first
git stash push -u -m "WIP before recovery"

# See Graphite's view (source of truth for parents)
gt status

# Visual tree
gt ls

# Compare with expected structure
# Document which branches are wrong

Questions to answer:

Which branches have wrong parents?
Which files ended up in wrong branches?
What should the correct stack structure be?

Phase 2: Fix Branch Relationships

Move branches to correct parents:

# Move branch to correct parent
gt move --source wrong-branch --onto correct-parent

# Example: branch should be child of feature-a, not sibling
gt move --source feature-b --onto feature-a

For complex reorganization:

# Move multiple branches
gt move --source branch-1 --onto main
gt move --source branch-2 --onto branch-1
gt move --source branch-3 --onto branch-2

Phase 3: Insert Missing Branches

If branches need to be inserted:

# Go to parent branch
gt checkout parent-branch

# Insert new branch between parent and existing child
gt create 'missing-branch' --insert -am "feat: description"

Phase 4: Redistribute Files

Move files to correct branches:

# Go to top of stack
gt top

# Restore stashed work
git stash pop

# Stage specific files
git add path/to/file.ts

# Commit to correct downstack branch
gt modify --into target-branch -m "feat: move file to correct branch"

# Repeat for each misplaced file

Alternative using absorb (when files should go to original branches):

gt top
git add .
gt absorb -a

Phase 5: Restack and Verify

# Rebase all branches onto updated parents
gt restack

# Verify structure
gt status
gt ls

# Check each branch has correct files
gt checkout branch-1
ls -la

gt checkout branch-2
ls -la

Phase 6: Submit Fixed Stack

# Submit the corrected stack
gt submit --stack

Review PRs to ensure:

Correct files in each PR
Correct parent/child relationships
PR titles match content

Emergency Recovery

When normal recovery fails:

# Try automatic repair
gt repo fix

# If that fails, nuclear option:
# 1. Note current branch contents
# 2. Create fresh branches
# 3. Manually move files
# 4. Rebuild stack from scratch

Metadata Repair

When Graphite's tracking diverges from Git:

# Add branch created outside Graphite
gt track branch-name
# Prompts to select correct parent

# Remove branch from Graphite tracking
gt untrack branch-name

Prevention

To avoid future corruption:

Single orchestrator - Only one agent performs git operations
Explicit commits - Use gt modify --into for specific branches
Regular status checks - Run gt status before complex operations
Atomic stacks - Keep stacks focused (3-5 branches max)

See the multi-agent-vcs skill for multi-agent coordination patterns.

3.3 KiB Raw Blame History