jj / How jj util diff works

How jj util diff works

jj util diff compares two files on disk with jj's own diff renderers, outside any repository.

On this page
  1. 1. Command-line surface
  2. 3. End-to-end flow
  3. 4. Core architecture touchpoints

In short: it reads both files, wraps each as a resolved one-sided Merge, and passes them to the same show_diff_bytes the repo diff commands use for file content. Only the Git and color-words formats print anything; the summary-style formats are hidden, and an external --tool prints nothing yet.

The command is cmd_util_diff. Its help text: "Compare two files on disk" (source). It is the Diff variant of UtilCommand (source, dispatch).

1. Command-line surface

ArgumentTypeDefaultMeaning
PATH1, PATH2 (positional, required)pathsnone"First path to compare", "Second path to compare" (source).
Diff format flagsflagsui.diff-formatterThe shared DiffFormatArgs, such as --git, --color-words and --tool. --summary, --stat, --types and --name-only are hidden, and -w/-b are added as short forms of --ignore-all-space/--ignore-space-change (source).

Format flags and defaults are covered on the jj diff page. The global flags are on the CLI page.

3. End-to-end flow

jj util diff: call flow cmd_util_diff resolves the diff formats and conflict materialization options from settings, reads both files with fs::read into resolved Merge values, requests the pager, and calls show_diff_bytes. That returns early if the contents are equal, skips the short formats, renders Git or color-words output, and does nothing for an external tool. diff_formats_for; materialize options ui.conflict-marker-style, merge options fs::read both → Merge::resolved read error names the path request_pager; show_diff_bytes labelled "diff" on stdout equal → nothing; per format: git, color-words; short and tool skipped

4. Core architecture touchpoints

PieceRole here
diff_util::show_diff_bytesRenders two byte contents with the chosen formats. Short formats are skipped because "printing dummy file path wouldn't be useful"; DiffFormat::Tool has a TODO and prints nothing (source, source).
MergeEach file is a resolved one-term merge, so the renderers that also handle conflicted files can be reused (source). Merges are covered on the conflicts page.
Repo, working copy, operation logNot touched: the command never asks for a workspace. Identical files print nothing; different ones print a normal Git or color-words diff (test).