ait snapshot — Complete Reference

ait snapshot
ait snapshot create
ait snapshot list
ait snapshot show
ait snapshot diff
ait snapshot restore-lines
ait snapshot revert
ait snapshot replay
ait snapshot ancestry
ait snapshot is-ancestor
ait snapshot merge-base

Create, inspect, compare, and query immutable local Snapshots. Snapshot create advances the current Line head; restore-lines, revert, and replay modify only the current workspace and never create a Snapshot, move a Line head, or mutate remote authority.

Usage: ait snapshot <COMMAND>

Commands:
  create         Capture the managed workspace as a new Snapshot.
  list           List repository-wide local Snapshot history.
  show           Inspect one immutable local Snapshot.
  diff           Compare two immutable local Snapshots.
  restore-lines  Preview or apply an exact line range from one Snapshot into the workspace.
  revert         Remove the current head Snapshot's recorded delta from the workspace.
  replay         Apply one Snapshot's recorded delta to the current Line workspace.
  ancestry       Query bounded Snapshot ancestors or descendants using metadata-only DAG traversal.
  is-ancestor    Test DAG ancestry; exits 0 when true, 1 when false, and 2 on lookup or storage errors.
  merge-base     Find the deterministic best common Snapshot ancestor.
  help           Print this message or the help of the given subcommand(s)

Options:
  -h, --help
          Print help (see a summary with '-h')

Capture the projected managed workspace as a new immutable local Snapshot and advance the current Line head. This command does not publish remote state.

Usage: ait snapshot create [OPTIONS]

Options:
      --message <MESSAGE>
          Record an optional human-readable Snapshot message.

      --json
          Emit the complete stable machine-readable creation payload.

  -h, --help
          Print help (see a summary with '-h')

List local Snapshots across every Line without modifying repository state. Text and JSON output are bounded to the recent view by default; --all emits complete history.

Usage: ait snapshot list [OPTIONS]

Options:
      --all
          Show complete Snapshot history instead of the bounded recent text or JSON view.

      --json
          Emit the stable machine-readable Snapshot list.

  -h, --help
          Print help (see a summary with '-h')

Inspect one Snapshot resolved from an exact Snapshot ID or local AIT Tag. Default text includes identity and bounded primary-parent change evidence; --files expands the complete tree inventory. JSON is always complete.

Usage: ait snapshot show [OPTIONS] <SNAPSHOT_OR_TAG>

Arguments:
  <SNAPSHOT_OR_TAG>
          Exact immutable Snapshot ID or local AIT Tag to inspect.

Options:
      --files
          Show the complete Snapshot tree inventory in text output; JSON is always complete.

      --json
          Emit the complete stable machine-readable Snapshot payload.

  -h, --help
          Print help (see a summary with '-h')

Compare two Snapshots resolved from exact Snapshot IDs or local AIT Tags. Structural file changes are reported by default; --include-text adds bounded text diffs for eligible modified files. This command is read-only.

Usage: ait snapshot diff [OPTIONS] <OLD_SNAPSHOT_OR_TAG> <NEW_SNAPSHOT_OR_TAG>

Arguments:
  <OLD_SNAPSHOT_OR_TAG>
          Exact Snapshot ID or local AIT Tag for the old side.

  <NEW_SNAPSHOT_OR_TAG>
          Exact Snapshot ID or local AIT Tag for the new side.

Options:
      --include-text
          Include bounded line-oriented text diffs for eligible modified files.

      --max-bytes <BYTES>
          Maximum old or new file size admitted for text diff generation; requires --include-text.
          
          [default: 128000]

      --json
          Emit the complete stable machine-readable diff payload.

  -h, --help
          Print help (see a summary with '-h')

Read one exact immutable Snapshot ID and preview replacement of the same existing regular workspace path at one positive 1-based line or inclusive range. Only --yes applies the selected lines; the command never creates a Snapshot or moves a Line head.

Usage: ait snapshot restore-lines <SNAPSHOT_ID> <PATH> (--line <N> | --start <N> --end <N>) [--yes] [--json]

Arguments:
  <SNAPSHOT_ID>
          Exact immutable Snapshot ID to read line content from.

  <PATH>
          Existing regular workspace file to update.

Options:
      --line <LINE>
          Select one 1-based workspace line.

      --start <START_LINE>
          Start of one inclusive 1-based line range.

      --end <END_LINE>
          End of one inclusive 1-based line range.

      --yes
          Apply the selected Snapshot lines; omission is always a read-only preview.

      --json
          Emit the complete stable machine-readable preview or apply result.

  -h, --help
          Print help (see a summary with '-h')

Remove one Line Snapshot's primary-parent-to-revision delta from the current workspace. The requested Snapshot must be the current Line head. This does not create a Snapshot, move the current Line head, or mutate remote state.

Usage: ait snapshot revert [OPTIONS] <SNAPSHOT_OR_TAG>

Arguments:
  <SNAPSHOT_OR_TAG>
          Current Line head Snapshot, identified by exact ID or local AIT Tag.

Options:
      --force
          Overwrite unsaved changes on paths selected by the Snapshot delta.

      --dry-run
          Preview affected paths and overwrite risk without modifying the workspace.

      --json
          Emit the complete stable machine-readable workspace plan or result.

  -h, --help
          Print help (see a summary with '-h')

Apply one non-root Line Snapshot's primary-parent-to-revision delta to the current Line workspace. This does not create a Snapshot, move the current Line head, or mutate remote state.

Usage: ait snapshot replay [OPTIONS] <SNAPSHOT_OR_TAG>

Arguments:
  <SNAPSHOT_OR_TAG>
          Non-root Snapshot whose recorded delta will be applied to the workspace.

Options:
      --force
          Overwrite unsaved changes on paths selected by the Snapshot delta.

      --dry-run
          Preview affected paths and overwrite risk without modifying the workspace.

      --json
          Emit the complete stable machine-readable workspace plan or result.

  -h, --help
          Print help (see a summary with '-h')

Query deterministic topological Snapshot ancestry resolved from an exact Snapshot ID or local AIT Tag. Ancestors across all parents are the default; direction, first-parent traversal, depth, and result bounds are explicit. The query Snapshot itself is excluded.

Usage: ait snapshot ancestry [OPTIONS] <SNAPSHOT_OR_TAG>

Arguments:
  <SNAPSHOT_OR_TAG>
          Exact Snapshot ID or local AIT Tag at the query boundary.

Options:
      --ancestors
          Traverse ancestors; this is the default direction.

      --descendants
          Traverse descendants instead of ancestors.

      --first-parent
          Follow only ordinal-zero parent edges instead of all parents.

      --max-depth <DEPTH>
          Stop traversal after this positive edge depth.
          
          [default: 10000]

      --limit <COUNT>
          Admit at most this positive number of results.
          
          [default: 10000]

      --all
          Show every result admitted by --limit in text output instead of the nearest 20; JSON already includes every admitted result.

      --json
          Emit the complete stable machine-readable bounded query payload.

  -h, --help
          Print help (see a summary with '-h')

Test whether one Snapshot is reachable as an ancestor of another across the complete parent DAG. Each input accepts an exact Snapshot ID or local AIT Tag. The command exits 0 when true, 1 when false, and 2 on lookup or storage errors.

Usage: ait snapshot is-ancestor [OPTIONS] <OLDER_SNAPSHOT_OR_TAG> <NEWER_SNAPSHOT_OR_TAG>

Arguments:
  <OLDER_SNAPSHOT_OR_TAG>
          Candidate ancestor, identified by exact Snapshot ID or local AIT Tag.

  <NEWER_SNAPSHOT_OR_TAG>
          Candidate descendant, identified by exact Snapshot ID or local AIT Tag.

Options:
      --json
          Emit the stable machine-readable ancestry decision and distance.

  -h, --help
          Print help (see a summary with '-h')

Find the best common ancestor of two Snapshots resolved from exact Snapshot IDs or local AIT Tags. The default emits one deterministic best base; --all emits every equally best base. The command exits 0 when a base exists, 1 when none exists, and 2 on lookup or storage errors.

Usage: ait snapshot merge-base [OPTIONS] <LEFT_SNAPSHOT_OR_TAG> <RIGHT_SNAPSHOT_OR_TAG>

Arguments:
  <LEFT_SNAPSHOT_OR_TAG>
          Left Snapshot, identified by exact ID or local AIT Tag.

  <RIGHT_SNAPSHOT_OR_TAG>
          Right Snapshot, identified by exact ID or local AIT Tag.

Options:
      --all
          Emit every equally best common ancestor in deterministic order.

      --json
          Emit the complete stable machine-readable merge-base result.

  -h, --help
          Print help (see a summary with '-h')