devansh-rookie/jj

Purpose and workspace layout

Jujutsu (jj) is a Rust command-line version-control system. It separates VCS semantics from physical storage; the production backend stores commits/files in Git while Jujutsu owns higher-level metadata such as bookmarks, operations, and workspace state. Cargo workspace roots are Cargo.toml, with the user executable in cli/ and reusable core in lib/.

CLI entry and command dispatch

The jj binary starts at cli/src/main.rs, with shared CLI initialization and public wiring in cli/src/lib.rs. Command registration/dispatch is centralized in cli/src/commands/mod.rs; individual command modules implement user workflows, including history rewriting (cli/src/commands/rebase.rs), Git interoperability (cli/src/commands/git/mod.rs), and operation recovery (cli/src/commands/operation/mod.rs).

CLI code is the boundary for argument parsing, configuration/UI, repository opening, working-copy lifecycle, and translating domain failures to terminal output.

Core repository model and transactions

The domain layer models commits, trees, refs/views, operations, repositories, and workspaces. Key ownership and mutation boundaries are lib/src/repo.rs, lib/src/transaction.rs, and lib/src/operation.rs. Commands mutate a transactional repository view, then record a new operation snapshot; this supports operation log, undo/restore, and safe state evolution rather than in-place untracked mutation.

Storage, Git interoperability, and metadata

Storage is abstracted behind backend/store interfaces in lib/src/backend.rs and lib/src/store.rs. The production Git implementation is lib/src/git_backend.rs, with Git integration and remote-oriented behavior in lib/src/git.rs. Git stores commit/file objects and enables ordinary Git remotes; Jujutsu-specific operation, workspace, and head metadata are persisted through separate stores such as lib/src/op_store.rs and lib/src/workspace_store.rs. Git is the material external service/protocol; gitoxide is identified by the README as the Git Rust library.

Working-copy snapshot boundary

Jujutsu treats the working copy as a commit. Filesystem-facing behavior is isolated in lib/src/working_copy.rs and the local implementation lib/src/local_working_copy.rs; CLI snapshot orchestration is in cli/src/commands/util/snapshot.rs. The normal control flow is: snapshot filesystem changes into the working-copy commit, execute a repository transaction, commit an operation, then update the filesystem if the working-copy commit changed. This centralization lets most commands operate on repository commits rather than directly manipulating dirty files.

Revision graph, rewriting, and conflicts

Commit selection and graph evaluation are handled by the revset language and index: lib/src/revset.rs, lib/src/revset_parser.rs, and lib/src/default_index/revset_engine.rs. History transformations—including descendant rebasing—are rooted in lib/src/rewrite.rs. Merge/conflict state is domain data rather than an interrupted command condition, implemented by lib/src/conflicts.rs, lib/src/merge.rs, and lib/src/tree_merge.rs; rewritten descendants can therefore retain or propagate resolvable conflicts.

Configuration, presentation, and extensibility

Layered configuration is resolved in lib/src/config_resolver.rs and surfaced by cli/src/config.rs; built-in defaults live under cli/src/config/. User-facing graph/log/diff output combines CLI formatting with templates, notably cli/src/graphlog.rs, cli/src/templater.rs, and cli/src/template_parser.rs. Extension seams are explicit in examples and interfaces for custom backends, commands, templaters, and working copies under cli/examples/.

Runtime and supporting infrastructure

Primary runtime is native Rust/Cargo on Unix and Windows, with platform-specific locking in lib/src/lock/unix.rs and lib/src/lock/windows.rs. Optional integrations include Watchman filesystem monitoring (lib/src/fsmonitor.rs), external merge/diff tools (cli/src/merge_tools/), GPG/SSH signing (lib/src/gpg_signing.rs, lib/src/ssh_signing.rs), and Gerrit upload (cli/src/commands/gerrit/upload.rs). Documentation is separately built as an Astro site under web/docs/; it is not part of the VCS runtime.