checkpoint

/checkpoint - Git Checkpoint Management

Create, restore, list, or clean git checkpoints.

Command: $ARGUMENTS

When to Use

• About to start a risky refactoring
• Before deleting or restructuring modules
• During multi-step implementations (checkpoint between steps)
• Before running destructive git operations
• NOT for: every small edit (too noisy)

Operations

Create Checkpoint

/checkpoint create feature-auth

Workflow:

1. Stage all changes
2. Commit with checkpoint message
3. Create tag

git add -A
git commit -m "checkpoint: [name]"
git tag checkpoint/[name]

Output:

──── Checkpoint Created ────
Name: checkpoint/feature-auth
Commit: abc1234
Files: 5 changed
Time: 2024-01-15 14:30:22

Create Restore Point

/checkpoint restore-point

Creates a timestamp-based restore point before major operations.

git tag restore-point/$(date +%Y%m%d-%H%M%S)

Output:

──── Restore Point Created ────
Tag: restore-point/20240115-143022
Use to rollback entire session if needed.

List Checkpoints

/checkpoint list

git tag -l "checkpoint/*" | sort -V
git tag -l "restore-point/*" | sort

Output:

──── Checkpoints ────
Checkpoints:
  checkpoint/task-1        (2024-01-15 14:20)
  checkpoint/task-2        (2024-01-15 14:25)
  checkpoint/feature-auth  (2024-01-15 14:30)

Restore Points:
  restore-point/20240115-141500
  restore-point/20240115-143022

Restore Checkpoint

/checkpoint restore feature-auth

Warning: This will discard uncommitted changes!

# Confirm with user first
git reset --hard checkpoint/[name]

Output:

──── Checkpoint Restored ────
Restored to: checkpoint/feature-auth
Commit: abc1234
Current state matches checkpoint.

Full Rollback

/checkpoint rollback 20240115-143022

Rollback to a restore point (undoes all work since).

git reset --hard restore-point/[timestamp]

Clean Checkpoints

/checkpoint clean

Remove all checkpoint tags (keeps restore points).

git tag -l "checkpoint/*" | xargs -n 1 git tag -d

Output:

──── Checkpoints Cleaned ────
Removed: 5 checkpoint tags
Kept: 2 restore points

Clean All

/checkpoint clean-all

Remove ALL checkpoints and restore points.

git tag -l "checkpoint/*" | xargs -n 1 git tag -d
git tag -l "restore-point/*" | xargs -n 1 git tag -d

Default Behavior

If no argument provided:

/checkpoint

Creates a timestamped checkpoint:

checkpoint/auto-20240115-143022

Usage in Workflow

Before Risky Changes

/checkpoint restore-point
# Make risky changes
# If it fails:
/checkpoint rollback [timestamp]

During Feature Development

/checkpoint create step-1
# Work on step 2
/checkpoint create step-2
# If step 2 is wrong:
/checkpoint restore step-1

After Session

/checkpoint clean  # Remove task checkpoints
# Keep restore points for safety

Output

──── /checkpoint ────
Operation: [create|restore|list|clean]
[Operation details]

Anti-Rationalization

Excuse	Reality
"I don't need a checkpoint, it's a small change"	Small changes break things too. A checkpoint takes 2 seconds, a rollback without one takes hours.
"Git history is enough"	Checkpoints are labeled save points - faster than hunting through git reflog.
"I'll just undo if something goes wrong"	You can't undo what you can't identify. Checkpoints mark the exact safe state.

Rules

1. Always confirm before restore - Destructive operation
2. Create restore point before major work
3. Clean checkpoints after successful completion
4. Keep restore points until merge