jj / How jj util snapshot works

How jj util snapshot works

jj util snapshot does the working-copy snapshot almost every command does on startup, and nothing else.

On this page
  1. 1. Command-line surface
  2. 3. End-to-end flow
  3. 4. Core architecture touchpoints

In short: it calls the same workspace loader as every other command and reports whether that changed the repo's operation. Upstream suggests it for scripts, to keep the operation that captures the user's file edits separate from the operations the script's own commands create (source).

The command is cmd_util_snapshot. Its help text: "Snapshot the working copy if needed" (source). It is the Snapshot variant of UtilCommand (source, dispatch).

1. Command-line surface

No arguments: UtilSnapshotArgs is empty (source). It doesn't print the new operation's id; upstream points scripts at jj op log --no-graph --limit 1 -T id for that (source). The global flags are on the CLI page.

3. End-to-end flow

jj util snapshot: call flow cmd_util_snapshot calls workspace_helper_with_stats. That loads the workspace and repo; if the working copy is writable it takes the Git import/export lock and snapshots, updating a stale working copy first if snapshot.auto-update-stale is set. It returns whether the repo's operation id changed. The command prints the snapshot stats, then "Snapshot complete." or "No snapshot needed." load workspace and repo not writable → return, no snapshot snapshot_impl stale + auto-update-stale → recover changed = op id differs old repo vs. new repo print stats; status line "Snapshot complete." / "No snapshot needed."

4. Core architecture touchpoints

PieceRole here
workspace_helper_with_statsThe shared startup path. Ordinary commands reach it through workspace_helper, which drops the "changed" flag (source); this command is the one that reports it.
is_working_copy_writableFalse with --ignore-working-copy or an --at-op other than @, and then no snapshot is taken.
Working copy, operation log"Snapshot complete." means the snapshot moved the repo to a new operation; "No snapshot needed." means the operation id is unchanged (source, tests). How a snapshot works is on the working copy page.