GBM — Automatic Project Checkpointing and Recovery

GBM records saved project files locally and restores earlier versions without Git commits. Python 3.10+; no runtime dependencies. This implementation uses portable filesystem polling and argparse rather than the proposed Watchdog and Typer dependencies. Windows is the tested platform; Linux/macOS code paths require validation.

Install

From this directory:

python -m pip install .
gbm --help

Or install the wheel from dist. If your Python Scripts folder is not on PATH, use python -m gbm in place of gbm. Source checkout usage also works from this directory without installation.

Use

Open a terminal in the project to protect:

gbm watch                 # Initial checkpoint; detached background process
gbm status                # Process liveness + recent heartbeat
gbm undo main.py          # Previous distinct recorded file version
gbm undo main.py --minutes 5 # Jump to the last checkpoint at/before five minutes ago
gbm redo main.py          # Reapply file undo; supports multiple levels
gbm undo                  # Preview affected count and confirm project undo
gbm undo --yes            # Project undo without interactive confirmation
gbm stop                  # Capture current state, stop monitoring
gbm recover               # Roll back an interrupted restore

watch returns after the background process starts. It runs as your user, without a visible console window on Windows. It is not an operating-system service and does not restart at login. Run watch again after reboot or a watcher failure. Errors are written to .gbm/watcher.log.

Commands discover the nearest ancestor with .gbm; otherwise watch initializes the current directory. File arguments are relative to the current working directory. Checkpoints include additions and deletions, binary contents and empty files. A rename is recorded as deletion plus addition. Unsaved editor buffers are not recorded.

Example: start watching with main.py containing print(1), save print(2), wait about three seconds, then run gbm undo main.py. The file returns to print(1); gbm redo main.py restores print(2).

History and recovery semantics

.gbm/history.db stores full content manifests and operation metadata; .gbm/objects stores deduplicated SHA-256 objects. History persists across terminal sessions. There is no automatic pruning or size limit; disk usage grows with unique contents.

The default scan interval is 0.5 seconds with two seconds of inactivity before a checkpoint. Files are read and hashed on each scan, so this release is intended for small to medium source trees. Rapid intermediate versions between scans are not guaranteed to be captured. Changes that never settle are saved when stop is called or a restore is requested.

Recovery captures pending changes first. File undo walks the distinct versions for that file; redo follows its undo stack. A new checkpointed edit to a file clears that file's redo stack. Unrelated edits retain it. Project undo walks backward through automatic project checkpoints, resets file redo stacks, and restores the whole monitored manifest. File restores do not advance the automatic project checkpoint sequence. Safety checkpoints preserve the state before every restoration and are excluded from ordinary undo navigation. There is no project redo command or general safety-checkpoint browser in this release.

Restore plans compare the current manifest immediately before application. A mismatch aborts before project writes. GBM serializes its own operations with an OS file lock, checks object hashes, writes each file with atomic replacement, verifies the final manifest, and keeps a durable pending-operation journal. A failed or interrupted restore blocks further checkpointing/restores until gbm recover rolls back to its pre-restore state. Recovery first preserves the currently visible contents as another safety checkpoint. A multi-file restore is not a filesystem-wide atomic transaction. External editors do not honor GBM's lock: avoid saving files during restoration; races during the write phase can still occur.

Scope and exclusions

Edit .gbm/config.json while monitoring is stopped. exclude is a list of shell-style patterns matched against each path component. .gbm and .git are always excluded. Defaults also exclude node_modules, .venv, venv, __pycache__, dist, build, .pytest_cache, .mypy_cache, .env, .env.*, *.pem, *.key, *.pfx, *.pyc, *.swp, and *.tmp.

These patterns are not a secret scanner. Other sensitive files will be stored unless you exclude them. Objects are not encrypted. Removing an exclusion or changing scope after recording history can make older restores fail; keep the monitoring policy stable. GBM never intentionally traverses symbolic links or Windows junctions. Keep its internal storage private and do not modify it manually. Paths and history are trusted local data, not a security boundary against another process actively replacing filesystem entries.

For a conventional .git directory, initialization adds /.gbm/ to .git/info/exclude. For Git worktrees or before creating a Git repository, add .gbm/ to your .gitignore yourself.

Only file bytes and existence are versioned. Permissions, timestamps, alternate data streams, hard-link relationships and empty directories are not preserved. File/directory type collisions or locked files can prevent a restore; the journal permits recovery after resolving the obstruction. No cloud backup, project redo, GUI, encryption, history export, or production database recovery is included. GBM complements source control and backups.

Validate and publish

python -m unittest discover -s tests -v
python -m pip wheel . --no-deps --wheel-dir dist

Tests cover file/project history, repeated undo/redo, additions/deletions, preservation of pending edits, conflicts, object corruption, interruption recovery, exclusions, deduplication, and a real detached Windows watcher lifecycle.

The source is prepared for a GitHub repository, including MIT licensing and CI. The destination repository is https://github.com/SumanyuDeshpande/GBM. The implementation has not yet been pushed or published. Review this release before publication. Treat this as an initial implementation requiring broader real-project testing before relying on it as your only recovery mechanism.

Time-based file undo (1.1)

gbm undo main.py --minutes 5 restores only that file from the most recent automatic checkpoint at or before five minutes before the command starts. Fractional minutes work (--minutes 0.5 is 30 seconds). The selected checkpoint's local timestamp is displayed. If no checkpoint is old enough, GBM reports this without restoring anything; it never guesses an older version. If the file did not exist in the selected checkpoint, it is removed, with its current contents preserved for gbm redo main.py. Unrelated files stay unchanged. Redo reverses the entire jump in one command. Ordinary file undo after a jump continues backward from the selected checkpoint. A repeated time jump uses the current clock time, not the last undo position. Checkpoints record observed saved states, not exact historical filesystem contents between scans.