checkpoint

checkpoint is a command-history rollback helper.

Instead of filesystem snapshots, it reads your shell history, matches commands against reversible rules, and builds inverse commands to undo what you did.

Installation

curl -fsSL https://raw.githubusercontent.com/zane-lang/checkpoint/main/install.sh | bash

The script:

• Clones the repo to ~/.checkpoint
• Creates a Python virtual environment at ~/.checkpoint/.venv and installs coda-format into it
• Prompts whether to add checkpoint to PATH and write the shell history setup into your .bashrc / .zshrc

To add the shell setup manually, run:

checkpoint setup bash >> ~/.bashrc   # or zsh

What It Does

• Reads command history from your shell history file.
• Matches commands against rules in rules.coda.
• Builds inverse commands.
• Executes inverses in reverse order (LIFO), so rollback order makes sense.
• Stores named checkpoint boundaries in .checkpoints.coda.

Quick Usage

checkpoint set "installing-llvm"
checkpoint restore installing-llvm

Commands

checkpoint set [description]
checkpoint list
checkpoint restore
checkpoint restore <N>
checkpoint restore <description>
checkpoint restore -t <timestamp>
checkpoint restore --time <timestamp>
checkpoint rules
checkpoint setup [shell]
checkpoint help

checkpoint set [description]

Creates a restore boundary at the current history index.

• description is optional.
• Non-empty descriptions must be unique.
• Empty descriptions are allowed (restore these by timestamp).

Output includes:

• time (ISO timestamp; acts as checkpoint identifier)
• description
• history index

checkpoint list

Shows all saved checkpoints from .checkpoints.coda.

Each row includes:

• checkpoint timestamp
• history index
• description

checkpoint restore

Restores commands since the latest checkpoint.

checkpoint restore <N>

Restores from the last N commands in history.

checkpoint restore <description>

Restores commands since the checkpoint with that description.

checkpoint restore -t <timestamp> / --time <timestamp>

Restores commands since a specific checkpoint time.

Use this when:

• description is empty
• you want an exact checkpoint target

checkpoint rules

Prints loaded inverse rules from rules.coda.

checkpoint setup [shell]

Prints shell snippet to improve history behavior for checkpoint.

• auto-detects shell if omitted
• supports bash and zsh

Restore Behavior

Planning

checkpoint restore ... first builds a restore plan from matching rules.

Commands with no matching rule are skipped and summarized.

Execution Order

Inverses run in reverse order of original commands.

That means rollback behaves like stack pop (last change undone first).

sudo

If the original command starts with sudo:

• matching ignores the leading sudo
• inverse command is re-prefixed with sudo

Before execution, if any planned inverse needs sudo, checkpoint:

1. asks for confirmation
2. runs sudo -v once
3. aborts before running inverses if auth is denied

Post-Restore Cleanup

After restore runs, checkpoint:

• removes restored original commands from history file
• removes checkpoints created after the restore boundary

Rules File

Rules live in rules.coda.

Each rule maps a match pattern to an inverse template.

Example:

rules [
    key inverse

    "apt install $$"      "apt remove $$"
    "brew install $$"     "brew uninstall $$"
    "mkdir $"             "rmdir $"
    "ln -s $src $dst"     "unlink $dst"
]

Capture Syntax

• $name: single named token
• $: single anonymous token
• $$: variadic capture (remaining tokens)

Checkpoint Storage

Checkpoints are stored in .checkpoints.coda as a keyed table.

Key = timestamp.

Example:

checkpoints [
    key index description

    "2026-04-09T20:31:16" 1313 "installing-llvm"
    "2026-04-09T21:01:16" 1329 ""
]

Typical Workflow

# start risky set of changes
checkpoint set "before packages"

sudo apt install foo bar
brew install baz

# rollback to boundary
checkpoint restore "before packages"

Or restore by exact time:

checkpoint list
checkpoint restore --time 2026-04-09T20:31:16

Notes

• If no checkpoint exists, checkpoint restore falls back to last 50 commands.
• History source is your shell history file; keeping shell history flushed helps accuracy.