# devansh-rookie/jj architecture

> Architecture diagram of the GitHub repository devansh-rookie/jj, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/devansh-rookie/jj
- Repository: https://github.com/devansh-rookie/jj

## Overview

#### 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.

Main entry points: [`cli/src/commands/rebase.rs`](https://github.com/devansh-rookie/jj/blob/main/cli/src/commands/rebase.rs) (Command workflows), [`lib/src/repo.rs`](https://github.com/devansh-rookie/jj/blob/main/lib/src/repo.rs) (Repository view), [`cli/src/lib.rs`](https://github.com/devansh-rookie/jj/blob/main/cli/src/lib.rs) (CLI initialization), [`lib/src/transaction.rs`](https://github.com/devansh-rookie/jj/blob/main/lib/src/transaction.rs) (Repository transaction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI runtime"]
  node_binary["jj binary<br/>Rust executable<br/>[main.rs]"]
  node_cli_lib["CLI initialization<br/>CLI wiring<br/>[lib.rs]"]
  node_dispatch["Command dispatch<br/>command registry<br/>[mod.rs]"]
  node_workflows["Command workflows<br/>command modules<br/>[rebase.rs]"]
end

subgraph group_domain["Repository domain"]
  node_repo["Repository view<br/>domain model<br/>[repo.rs]"]
  node_transaction["Repository transaction<br/>mutation boundary<br/>[transaction.rs]"]
  node_operation["Operation snapshots<br/>operation model<br/>[operation.rs]"]
end

subgraph group_storage["Storage and Git"]
  node_store["Store interfaces<br/>storage abstraction<br/>[store.rs]"]
  node_backend["Backend interfaces<br/>storage abstraction<br/>[backend.rs]"]
  node_git_backend[("Git backend<br/>production backend<br/>[git_backend.rs]")]
  node_git{{"Git integration<br/>Git protocol<br/>[git.rs]"}}
  node_metadata[("Metadata stores<br/>Jujutsu metadata<br/>[op_store.rs]")]
end

subgraph group_worktree["Working copy"]
  node_snapshot_orchestrator["Snapshot orchestration<br/>CLI utility<br/>[snapshot.rs]"]
  node_working_copy["Working-copy interface<br/>filesystem boundary<br/>[working_copy.rs]"]
  node_local_working_copy["Local working copy<br/>filesystem implementation"]
end

subgraph group_query["Revision and rewrite"]
  node_revset["Revset evaluation<br/>revision query<br/>[revset.rs]"]
  node_rewrite["History rewriting<br/>graph transformation<br/>[rewrite.rs]"]
  node_conflicts["Merge conflicts<br/>domain state<br/>[conflicts.rs]"]
end

subgraph group_support["Configuration and integrations"]
  node_config["Layered configuration<br/>[config_resolver.rs]"]
  node_presentation["Graph, templates, and output<br/>presentation<br/>[graphlog.rs]"]
end

node_binary -->|"starts"| node_cli_lib
node_cli_lib -->|"initializes"| node_dispatch
node_dispatch -->|"routes commands"| node_workflows
node_workflows -->|"uses"| node_snapshot_orchestrator
node_snapshot_orchestrator -->|"snapshots and updates"| node_local_working_copy
node_local_working_copy -->|"implements"| node_working_copy
node_snapshot_orchestrator -->|"wraps mutation"| node_transaction
node_workflows -->|"opens and reads"| node_repo
node_workflows -->|"selects commits"| node_revset
node_workflows -->|"transforms history"| node_rewrite
node_transaction -->|"mutates view"| node_repo
node_transaction -->|"commits snapshot"| node_operation
node_repo -->|"uses"| node_store
node_store -->|"delegates objects"| node_backend
node_backend -->|"implemented by"| node_git_backend
node_git_backend -->|"uses Git objects"| node_git
node_operation -->|"persists"| node_metadata
node_repo -->|"loads state"| node_metadata
node_revset -->|"evaluates repository graph"| node_repo
node_rewrite -->|"propagates conflict state"| node_conflicts
node_cli_lib -->|"loads"| node_config
node_workflows -->|"renders results"| node_presentation

click node_binary "https://github.com/devansh-rookie/jj/blob/main/cli/src/main.rs"
click node_cli_lib "https://github.com/devansh-rookie/jj/blob/main/cli/src/lib.rs"
click node_dispatch "https://github.com/devansh-rookie/jj/blob/main/cli/src/commands/mod.rs"
click node_workflows "https://github.com/devansh-rookie/jj/blob/main/cli/src/commands/rebase.rs"
click node_snapshot_orchestrator "https://github.com/devansh-rookie/jj/blob/main/cli/src/commands/util/snapshot.rs"
click node_repo "https://github.com/devansh-rookie/jj/blob/main/lib/src/repo.rs"
click node_transaction "https://github.com/devansh-rookie/jj/blob/main/lib/src/transaction.rs"
click node_operation "https://github.com/devansh-rookie/jj/blob/main/lib/src/operation.rs"
click node_store "https://github.com/devansh-rookie/jj/blob/main/lib/src/store.rs"
click node_backend "https://github.com/devansh-rookie/jj/blob/main/lib/src/backend.rs"
click node_git_backend "https://github.com/devansh-rookie/jj/blob/main/lib/src/git_backend.rs"
click node_git "https://github.com/devansh-rookie/jj/blob/main/lib/src/git.rs"
click node_metadata "https://github.com/devansh-rookie/jj/blob/main/lib/src/op_store.rs"
click node_working_copy "https://github.com/devansh-rookie/jj/blob/main/lib/src/working_copy.rs"
click node_local_working_copy "https://github.com/devansh-rookie/jj/blob/main/lib/src/local_working_copy.rs"
click node_revset "https://github.com/devansh-rookie/jj/blob/main/lib/src/revset.rs"
click node_rewrite "https://github.com/devansh-rookie/jj/blob/main/lib/src/rewrite.rs"
click node_conflicts "https://github.com/devansh-rookie/jj/blob/main/lib/src/conflicts.rs"
click node_config "https://github.com/devansh-rookie/jj/blob/main/lib/src/config_resolver.rs"
click node_presentation "https://github.com/devansh-rookie/jj/blob/main/cli/src/graphlog.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_binary,node_cli_lib,node_dispatch,node_workflows toneBlue
class node_repo,node_transaction,node_operation toneAmber
class node_store,node_backend,node_git_backend,node_git,node_metadata toneMint
class node_snapshot_orchestrator,node_working_copy,node_local_working_copy toneRose
class node_revset,node_rewrite,node_conflicts toneIndigo
class node_config,node_presentation toneTeal
```

## Components

### CLI runtime

User command boundary and presentation.

- [jj binary](https://github.com/devansh-rookie/jj/blob/main/cli/src/main.rs): Rust executable · `cli/src/main.rs`
- [CLI initialization](https://github.com/devansh-rookie/jj/blob/main/cli/src/lib.rs): CLI wiring · `cli/src/lib.rs`
- [Command dispatch](https://github.com/devansh-rookie/jj/blob/main/cli/src/commands/mod.rs): command registry · `cli/src/commands/mod.rs`
- [Command workflows](https://github.com/devansh-rookie/jj/blob/main/cli/src/commands/rebase.rs): command modules · Includes rebase, Git, and operation recovery commands. · `cli/src/commands/rebase.rs`

### Repository domain

Transactional VCS semantics owned by Jujutsu.

- [Repository view](https://github.com/devansh-rookie/jj/blob/main/lib/src/repo.rs): domain model · Owns repository, refs, views, and workspace-facing state. · `lib/src/repo.rs`
- [Repository transaction](https://github.com/devansh-rookie/jj/blob/main/lib/src/transaction.rs): mutation boundary · Stages repository changes before recording an operation. · `lib/src/transaction.rs`
- [Operation snapshots](https://github.com/devansh-rookie/jj/blob/main/lib/src/operation.rs): operation model · Enables operation log, undo, and restore. · `lib/src/operation.rs`

### Storage and Git

Object storage, metadata persistence, and Git interoperability.

- [Store interfaces](https://github.com/devansh-rookie/jj/blob/main/lib/src/store.rs): storage abstraction · Abstracts commit and tree object storage. · `lib/src/store.rs`
- [Backend interfaces](https://github.com/devansh-rookie/jj/blob/main/lib/src/backend.rs): storage abstraction · `lib/src/backend.rs`
- [Git backend](https://github.com/devansh-rookie/jj/blob/main/lib/src/git_backend.rs): production backend · Stores commits and files as Git objects. · `lib/src/git_backend.rs`
- [Git integration](https://github.com/devansh-rookie/jj/blob/main/lib/src/git.rs): Git protocol · Supports Git interoperability and remotes through gitoxide. · `lib/src/git.rs`
- [Metadata stores](https://github.com/devansh-rookie/jj/blob/main/lib/src/op_store.rs): Jujutsu metadata · Persists operation, workspace, and head metadata separately from Git. · `lib/src/op_store.rs`

### Working copy

Filesystem snapshot and update boundary.

- [Snapshot orchestration](https://github.com/devansh-rookie/jj/blob/main/cli/src/commands/util/snapshot.rs): CLI utility · Coordinates pre-command snapshot and post-command update. · `cli/src/commands/util/snapshot.rs`
- [Working-copy interface](https://github.com/devansh-rookie/jj/blob/main/lib/src/working_copy.rs): filesystem boundary · `lib/src/working_copy.rs`
- [Local working copy](https://github.com/devansh-rookie/jj/blob/main/lib/src/local_working_copy.rs): filesystem implementation · Reads and updates the local filesystem. · `lib/src/local_working_copy.rs`

### Revision and rewrite

Revision selection, graph changes, and conflict modeling.

- [Revset evaluation](https://github.com/devansh-rookie/jj/blob/main/lib/src/revset.rs): revision query · Parses and evaluates commit-selection expressions using the index. · `lib/src/revset.rs`
- [History rewriting](https://github.com/devansh-rookie/jj/blob/main/lib/src/rewrite.rs): graph transformation · Rebases rewritten descendants and preserves graph evolution. · `lib/src/rewrite.rs`
- [Merge conflicts](https://github.com/devansh-rookie/jj/blob/main/lib/src/conflicts.rs): domain state · Represents resolvable conflict state in commits and trees. · `lib/src/conflicts.rs`

### Configuration and integrations

Cross-cutting configuration, presentation, and optional integrations.

- [Layered configuration](https://github.com/devansh-rookie/jj/blob/main/lib/src/config_resolver.rs): configuration · Resolves configuration for CLI behavior and UI. · `lib/src/config_resolver.rs`
- [Graph, templates, and output](https://github.com/devansh-rookie/jj/blob/main/cli/src/graphlog.rs): presentation · Renders logs, diffs, and terminal-facing results. · `cli/src/graphlog.rs`

## Connections

- jj binary → CLI initialization: starts
- CLI initialization → Command dispatch: initializes
- Command dispatch → Command workflows: routes commands
- Command workflows → Snapshot orchestration: uses
- Snapshot orchestration → Local working copy: snapshots and updates
- Local working copy → Working-copy interface: implements
- Snapshot orchestration → Repository transaction: wraps mutation
- Command workflows → Repository view: opens and reads
- Command workflows → Revset evaluation: selects commits
- Command workflows → History rewriting: transforms history
- Repository transaction → Repository view: mutates view
- Repository transaction → Operation snapshots: commits snapshot
- Repository view → Store interfaces: uses
- Store interfaces → Backend interfaces: delegates objects
- Backend interfaces → Git backend: implemented by
- Git backend → Git integration: uses Git objects
- Operation snapshots → Metadata stores: persists
- Repository view → Metadata stores: loads state
- Revset evaluation → Repository view: evaluates repository graph
- History rewriting → Merge conflicts: propagates conflict state
- CLI initialization → Layered configuration: loads
- Command workflows → Graph, templates, and output: renders results