Commits as directory trees

In short: a CommitTreeFile is built for every request. It looks the path up in the commit's MergedTree. Directories, regular files and symlinks work. Executable files show as ordinary files, submodules as files that fail on every access, and conflicted paths can't be read or stat'ed. A file's size is found by reading the whole file, and timestamps are always the Unix epoch.

This page covers src/commit_tree_file.rs, the only VirtualFile that reads repository content. For jj's own model of trees and conflicts, see Trees and Conflicts in the jj reference. The jj-lib links here are pinned to v0.43.0.

The type

AllCommitsPathMapper creates one for commits/<id>/… and for workspaces/<name>/…, passing the remaining segments as path (L56, L73). Nothing is cached: each FUSE request resolves its path again, so each one loads the commit again. commits/<id> itself is the commit's root, with an empty path.

Looking a path up

Every method starts the same way. It converts path with RepoPathBuf::from_relative_path, which rejects components like .. with InvalidPath. Then it reads the commit's tree:

• read, read_link and file_type call MergedTree::path_value. It walks the merged trees down to the parent directory and returns the Merge<Option<TreeValue>> for the last component. The lookup goes through Merge<Tree>::value, which resolves trivial merges, so a path that is the same on every side of a conflicted commit still comes back resolved. The root path returns the commit's tree IDs unchanged.
• Each method then calls as_resolved, which only succeeds for a single-term merge. Anything else is treated as a conflict, described below.
• list instead calls MergedTree::trees and Merge<Tree>::sub_tree_recursive to get the directory's own trees. If that finds no directory, it looks at path_value to choose between NotFound and NotADirectory (L67).

How each kind of path is presented

A resolved value is one of the four TreeValue variants, or absent. Errors become errnos through the FUSE adapter's mapping (fuse.rs).

Sources: file_type (L155), read (L48), read_link (L113), attributes (L129), the listing (L86) and the mode, which to_fuse picks from the type alone (fuse.rs). EISDIR for a symlink or a submodule comes from NotAFile; it doesn't mean they are directories.

Listing a directory

list gets the directory as a Merge<Tree>: one tree when it is resolved, one per term when it is conflicted. Where a term has no directory at that path, jj-lib substitutes an empty tree (sub_tree). It then:

1. takes the names from every term's entries_non_recursive and drops repeats with itertools' unique, so a name present on any side is listed once (L76);
2. builds each name's Merge<Option<TreeValue>> by mapping Tree::value over the terms (L82);
3. types it as above if that merge has one term, and as a file otherwise (L86);
4. collects everything into a Vec and returns it as a stream (L102).

Step 2 doesn't use Merge<Tree>::value, so it never resolves trivial merges. In a conflicted directory every term is kept, and every entry is listed as a file, even subdirectories and files that are the same on every side. A lookup of such an entry goes through path_value, which does resolve trivial merges, so it can report a different type than the listing did. In a resolved directory there is one term and the types are right.

The names come out in the order of the first term's entries, followed by names only the other terms have. Listing is the slow path for large directories: the Vec holds every entry, and readdir calls list again for each batch and skips to its offset. Upstream's TODOs at L80 and L102 note the lack of pagination.

Reading content

read passes the resolved File's id to Store::read_file and returns the backend's AsyncRead as is (L56). read_link does the same for a Symlink with Store::read_symlink and returns the target string as a path (L120).

The reader always starts at byte 0. For a FUSE read(offset, size), PathMappedVfs::read discards the first offset bytes and then reads size (vfs.rs), so reading a file from start to end in chunks reads the earlier part again for every chunk.

Sizes and attributes

attributes calls file_type first, so it looks the path up twice, and for a file a third time inside read.

Conflicts

jj stores a conflicted commit's tree as several trees (see tree merges). Here, a path whose value doesn't resolve, even trivially, is refused: read returns NotADirectory, file_type an I/O error “Conflicted path”, and read_link NotASymlink. Upstream's TODOs at L48 and L163 plan to show conflicts. Conflict markers are never materialized.

Derived from the code, not tested upstream: directories count too. The root of a conflicted commit has one tree per term, and so does every directory on the way down to a conflicted file, unless jj can resolve it trivially. file_type refuses those as well, so getattr on commits/<id> of a conflicted commit fails with EIO, even though list could list it.

Tests

All tests use the repository from test_helpers::setup_test_repo: file1.txt (“hello content 1”), dir/file2.txt and a symlink symlink → file1.txt, in one resolved commit.

No test covers executable files, submodules or conflicts.

Limitations