jj

jj architecture

A detailed, source-linked map of how Jujutsu (jj) works inside: its layers, every persisted schema, its core data structures, and how real commands move through them.

On this page
  1. The whole system on one page
  2. Architecture
  3. Commands
  4. Creating and editing changes
  5. Moving and combining changes
  6. Content and conflicts
  7. Inspecting history
  8. Operation log
  9. Bookmarks and tags
  10. Git and remotes
  11. Workspaces
  12. Signing
  13. Configuration
  14. Utilities and internals

The whole system on one page

The left side shows jj's layers, from the command line down to the files under .jj/. The right side shows the data model those layers store, with each arrow labelled by the field that links one object to the next. Every box links to the page that explains it, or to its source until that page exists.

jj architecture: layers and data model Left, top to bottom: the CLI (CliRunner, CommandHelper, WorkspaceCommandHelper, WorkspaceCommandTransaction) drives a Workspace, which loads a repo through RepoLoader into a ReadonlyRepo. Commands start a Transaction holding a MutableRepo and its View. The repo sits on stores: Store over a Backend (GitBackend or SimpleBackend), OpStore, OpHeadsStore, IndexStore and SubmoduleStore, with the WorkingCopy and WorkspaceStore beside them. All persist under the .jj directory. Right, the data model: an Operation points at a View by view_id and at parent operations; the View lists head_ids, bookmarks and the working-copy commit per workspace; each Commit has parents and a root_tree, which is a Merge of TreeIds; a Tree maps names to TreeValues, which are files, symlinks, subtrees or Git submodules. LAYERS DATA MODEL CLI · cli/src CliRunner main entry CommandHelper args, settings WorkspaceCommand Helper WorkspaceCommand Transaction WORKSPACE · lib/src/workspace.rs Workspace root, working copy, repo loader WorkspaceStore SimpleWorkspaceStore RepoLoader loads at op heads REPO · lib/src/repo.rs, transaction.rs, view.rs ReadonlyRepo one operation Transaction start → commit MutableRepo rewrites, rebases View view.rs wrapper STORES · traits in core/ and lib/, default impls in lib/ and default-index/ Store caching layer Backend GitBackend · SimpleBackend WorkingCopy LocalWorkingCopy OpStore SimpleOpStore OpHeadsStore SimpleOpHeadsStore IndexStore DefaultIndexStore SubmoduleStore DefaultSubmoduleStore ON DISK · .jj/ repo/store/ commits, trees, extra/ repo/op_store/ operations/, views/ repo/op_heads/heads/ one file per head repo/index/ segments/, op_links/, changed_paths/ working_copy/ tree_state, checkout repo/workspace_store/ index Operation metadata · commit_predecessors View (op_store) local_bookmarks · local_tags · remote_views Commit change_id · description · author · committer Merge<TreeId> alternating add / remove terms Tree sorted (name, TreeValue) entries TreeValue File · Symlink · Tree · GitSubmodule view_id parents head_ids wc_commit_ids[workspace] bookmark targets parents root_tree each term entries Tree(id)

The dashed arrow shows that the repo layer's View wraps and edits the stored view. Persistence follows the store names: the Backend (through Store) holds commits, trees and file contents; the OpStore holds operations and views; the OpHeadsStore records which operations are current heads; the IndexStore keeps a commit-graph index per operation; and the WorkingCopy records what's checked out on disk.

Architecture

  • How a command runs

    The lifecycle every command shares: dispatch, loading the workspace, snapshotting, transactions, and publishing the operation.

  • On-disk layout

    What lives where under .jj/, which component owns each path, and in what format.

  • Commits and change IDs

    The Commit object field by field, content-addressed commit IDs versus stable change IDs, and how commits are built and signed.

  • Trees, files and copies

    Tree objects, the TreeValue variants, merged trees and tree diffs, and copy tracking.

  • First-class conflicts

    Merge<T>, the alternating add/remove representation behind conflicted trees, refs and files.

  • The operation log

    Operations, their metadata, op heads, and how concurrent operations are detected and merged.

  • Views, bookmarks and tags

    The View each operation points at: heads, bookmarks, tags, remotes, Git refs and working-copy commits.

  • Repos, transactions and rewriting

    ReadonlyRepo, MutableRepo and Transaction, and how rewrites propagate to descendants.

  • The working copy

    Snapshot and checkout, the tree state file, file states, and stale working copies.

  • The commit index

    Index segments, the change-ID index, the changed-path index, and short ID prefixes.

  • Revset engine

    From revset text to evaluated commits: grammar, expression tree, symbol resolution and evaluation.

  • Storage backends

    The Backend trait, the Store caching layer, and the Git and simple backends.

  • Every schema

    All seven .proto files, every message, enum and field, and the Rust types they map to.

Commands

Every jj command and subcommand, traced from the CLI down into the core. The list comes from jj's own command definitions, and each summary is the command's own help text. Linked commands have a full page; the rest are still being written.

Creating and editing changes

  • jj new Create a new, empty change and (by default) edit it in the working copy
  • jj edit Sets the specified revision as the working-copy revision
  • jj describe Update the change description or other metadata [default alias: desc]
  • jj commit Update the description and create a new change on top [default alias: ci]
  • jj metaedit Modify the metadata of a revision without changing its content
  • jj next Move the working-copy commit to the child revision
  • jj prev Change the working copy revision relative to the parent revision

Moving and combining changes

  • jj rebase Move revisions to different parent(s)
  • jj squash Move changes from a revision into another revision
  • jj split Split a revision in two
  • jj absorb Move changes from a revision into the stack of mutable revisions
  • jj duplicate Create new changes with the same content as existing ones
  • jj abandon Abandon a revision
  • jj parallelize Parallelize revisions by making them siblings
  • jj simplify-parents Simplify parent edges for the specified revision(s).
  • jj arrange Interactively arrange the commit graph.
  • jj converge Converge divergent changes
  • jj revert Apply the reverse of the given revision(s)
  • jj restore Restore paths from another revision
  • jj diffedit Touch up the content changes in a revision with a diff editor

Content and conflicts

  • jj fix Update files with formatting fixes or other changes
  • jj run Run a command across a set of revisions.
  • jj resolve Resolve conflicted files with an external merge tool
  • jj file annotate Show the source change for each line of the target file.
  • jj file chmod Sets or removes the executable bit for paths in the repo
  • jj file delete Delete files from the given revision
  • jj file edit Edit the contents of a file in a revision
  • jj file list List files in a revision
  • jj file search Search for content in files
  • jj file show Print contents of files in a revision
  • jj file track Start tracking specified paths in the working copy
  • jj file untrack Stop tracking specified paths in the working copy
  • jj sparse edit Start an editor to update the patterns that are present in the working copy
  • jj sparse list List the patterns that are currently present in the working copy
  • jj sparse reset Reset the patterns to include all files in the working copy
  • jj sparse set Update the patterns that are present in the working copy

Inspecting history

  • jj log Show revision history
  • jj show Show revision metadata and diff
  • jj diff Compare file contents between two revisions
  • jj interdiff Show differences between the diffs of two revisions
  • jj status Show high-level repo status [default alias: st]
  • jj evolog Show how a change has evolved over time
  • jj root Show the current workspace root directory (shortcut for `jj workspace root`)
  • jj bisect run Run a given command to find the first bad revision

Operation log

Bookmarks and tags

Git and remotes

Workspaces

Signing

  • jj sign Cryptographically sign a revision
  • jj unsign Drop a cryptographic signature

Configuration

  • jj config edit Start an editor on a jj config file.
  • jj config gc Find and optionally delete repo and workspace config directories whose paths no longer exist.
  • jj config get Get the value of a given config option.
  • jj config list List variables set in config files, along with their values.
  • jj config path Print the paths to the config files
  • jj config set Update a config file to set the given option to a given value.
  • jj config unset Update a config file to unset the given option.

Utilities and internals