• Checkpoint refs: Captures workspace state into named Git checkpoint refs and applies them to the target directory.
• Path-scoped incremental sync: Replays only changed paths into the target after startup, then uses a full checkpoint restore on exit.
• Untracked by default: Workspace untracked files are included in checkpoints, while ignored files stay in the target.
• Watchexec-style watching: Serializes file events and coalesces bursts of changes into a single follow-up sync.
• Programmatic API: Use spotlight(), syncOnce(), and restore() directly from Node.js.

Install

npm install -g spotlight-testing

Requires Node.js 22+. macOS only.

Usage

Run from inside a git worktree. The target directory is inferred automatically:

spotlight-testing

Pass a linked worktree path from anywhere. The main checkout is still inferred automatically:

spotlight-testing on ./feature-branch

Explicitly set both worktree and target:

spotlight-testing on ./feature-branch --target ./main-repo

Stop syncing and restore the target:

spotlight-testing off

Stop spotlight if needed, then fetch, reset, and clean the target repo:

spotlight-testing reset

Reset to a specific ref without fetching:

spotlight-testing reset --to main --no-fetch

Check the current sync status:

spotlight-testing status

on, off, and status keep default output minimal. Use status when you need the full active-session details.

Target State

spotlight-testing on checkpoints the target root before spotlight starts. Plain spotlight-testing off restores that checkpoint, so tracked files, non-ignored untracked files, and the index return to their startup state.

spotlight-testing reset and spotlight-testing reset --to <ref> are the aggressive cleanup paths. They stop Spotlight if it is active, restore the saved checkpoint when one exists, then optionally fetch, hard-reset to the requested ref, and run git clean -fd so the target matches that ref except for ignored files.

Workspace changes are synced into the target through named Git checkpoint refs. After startup Spotlight replays only the changed paths into the target worktree, which keeps unrelated runtime files stable while still mirroring ongoing worktree edits.

Checkpoint restore is destructive only when spotlight stops. At shutdown the target is rewritten from the saved checkpoint using Git operations equivalent to reset --hard, read-tree -u, and clean -fd, followed by restoration of the saved index tree. Ignored files are left in place rather than checkpointed or rolled back.

syncOnce() follows the same checkpoint model in a one-shot destructive pass.

Options

Usage: spotlight-testing on [options] [worktree]

Arguments:
  worktree                     Path to the git worktree to sync from

Options:
  -t, --target <path>          Target directory to sync into
  -d, --debounce <ms>          Debounce interval in milliseconds (default: 300)
  -h, --help                   display help for command

Usage: spotlight-testing reset [options]

Options:
  --to <ref>                   Ref to reset to after fetch (default: <remote>/main)
  -t, --target <path>          Target directory to reset
  -r, --remote <name>          Remote to fetch from (default: "origin")
  --no-fetch                   Skip git fetch before reset
  -h, --help                   display help for command

API

import { spotlight, syncOnce, restore } from "spotlight-testing";

// Watch and sync continuously
spotlight({
  worktree: "/path/to/feature-branch",
  target: "/path/to/main-repo",
  debounce: 300,
});

// One-shot sync
const result = syncOnce("/path/to/feature-branch", "/path/to/main-repo");

// Restore the target to its original state
restore("/path/to/main-repo");

How It Works

1. Verifies the worktree and target share the same Git object database.
2. Saves a checkpoint of the target root before spotlight starts.
3. Creates a named checkpoint ref from the worktree.
4. Replays only the changed workspace paths into the target worktree during incremental sync.
5. Watches the worktree with a serialized change queue that behaves like watchexec.
6. Coalesces bursts of changes into the next checkpoint/restore cycle.
7. On exit, restores the saved target-root checkpoint with a full destructive restore.

Requirements

• Node.js 22+
• macOS
• Worktree and target must share the same Git common object database

License

MIT