jj / How jj sparse reset works

How jj sparse reset works

jj sparse reset sets the workspace's sparse patterns back to the single root pattern, so every file in the working-copy commit is checked out again. Commits and the operation log are untouched.

On this page
  1. 1. Command-line surface
  2. 2. Configuration
  3. 3. End-to-end flow
  4. 4. Core architecture touchpoints
  5. 5. Transaction and operation
  6. 6. Algorithm and invariants
  7. 7. Errors and edge cases
  8. 8. Worked example

In short: jj loads the workspace, which snapshots it as usual, locks the working copy, and replaces the patterns with [root], shown as .. The working copy writes every file that was outside the old patterns. It saves its state under the same operation ID and prints Added N files, modified 0 files, removed 0 files. It is jj sparse set --clear --add . in one word.

The command is cmd_sparse_reset: three lines that call the shared update_sparse_patterns_with with a closure returning vec![RepoPathBuf::root()] (source). The update step is described on the sparse set page.

1. Command-line surface

No arguments or flags (SparseResetArgs). The help text: "Reset the patterns to include all files in the working copy".

2. Configuration

None. The patterns live in the workspace's working-copy state, the sparse_patterns field of TreeState (see protobufs). The root pattern is also what a missing field means, for working copies older than the field (source), and what a new working copy starts with (source).

3. End-to-end flow

jj sparse reset: call flow cmd_sparse_reset loads the workspace through the shared lifecycle, which snapshots it. update_sparse_patterns_with locks the working copy; the closure ignores the old patterns and returns the root alone. set_sparse_patterns checks out every file not covered before and removes nothing, since the root covers everything. The working copy is saved under the old operation ID and the stats are printed. Shared lifecycle: load workspace and repo, snapshot the working copy (CLI page) lock the working copy start_working_copy_mutation new patterns = [root] the old ones are ignored set_sparse_patterns([root]) added = root − old: check out every file the old patterns left out removed = old − root: always empty finish(old operation ID): no operation print "Added N files, modified 0 files, removed 0 files" (nothing if N is 0)

4. Core architecture touchpoints

StructureRead / writeHowExplained on
Sparse patterns (TreeState)writeSet to the root alone (source).working-copy
Files on disk, file stateswriteEvery file of the working-copy commit outside the old patterns is written.working-copy
Working-copy commitreadSource of the checked-out files; never rewritten.trees
Operation loguntouchedSaved under the existing operation ID (source).operations

5. Transaction and operation

  • Transaction and operation: none; only the working-copy lock (source).
  • Before it: loading may record a snapshot working copy operation, as for any command.
  • Running it twice is harmless: the second time nothing is added, so nothing is printed.
  • jj undo doesn't apply; use jj sparse set to narrow again.

6. Algorithm and invariants

With new patterns [root], TreeState::set_sparse_patterns computes "added" as everything the old prefixes didn't cover and checks it out from the current tree; "removed" is empty, because the root prefix covers every path (PrefixMatcher). A new file's path that is already occupied on disk is skipped and reported.

Invariants: afterwards the patterns are exactly . and every tracked file of the working-copy commit is on disk. No file is deleted. Commits never change.

7. Errors and edge cases

MessageWhenSource
Warning: <n> of those updates were skipped because there were conflicting changes in the working copy.A file to check out would overwrite something already on disk.cli_util.rs
Failed to update working copy paths (internal error)Writing files failed.mod.rs
This command must be able to update the working copy.Run with --at-op, --ignore-working-copy or --no-integrate-operation.cli_util.rs
Concurrent working copy operation. Try again.The working copy changed between loading and locking.cli_util.rs
(no output)Already at the root pattern.cli_util.rs

8. Worked example

From upstream's test_sparse_manage_patterns. After jj sparse set --clear --add file2, only file2 of the commit's three files is on disk:

jj sparse reset: before and after Before: patterns file2; on disk only file2; the commit holds file1, file2 and file3. After jj sparse reset: patterns dot; on disk file1, file2 and file3; added 2 files, removed 0. The commit is the same. before patterns: file2 on disk: file2 in @: file1, file2, file3 after jj sparse reset patterns: . on disk: file1, file2, file3 in @: unchanged added 2, removed 0

Upstream's snapshot (source):

$ jj sparse reset
Added 2 files, modified 0 files, removed 0 files
$ jj sparse list
.