Configuration

These are the config settings available to jj/Jujutsu.

Config files and TOML

jj loads several types of config settings:

• The built-in settings. These cannot be edited. They can be viewed in the cli/src/config/ directory in jj's source repo.

• The user settings. These can be edited with jj config edit --user. User settings are located in the user config files, which can be found with jj config path --user.

• The repo settings. These can be edited with jj config edit --repo and are located in .jj/repo/config.toml.

• Settings specified in the command-line.

These are listed in the order they are loaded; the settings from earlier items in the list are overridden by the settings from later items if they disagree. Every type of config except for the built-in settings is optional.

You can enable JSON Schema validation in your editor by adding a $schema reference at the top of your TOML config files. See JSON Schema Support for details.

See the TOML site and the syntax guide for a detailed description of the syntax. We cover some of the basics below.

The first thing to remember is that the value of a setting (the part to the right of the = sign) should be surrounded in quotes if it's a string.

Dotted style and headings

In TOML, anything under a heading can be dotted instead. For example, user.name = "YOUR NAME" is equivalent to:

[user]
name = "YOUR NAME"

For future reference, here are a couple of more complicated examples,

# Dotted style
template-aliases."format_short_id(id)" = "id.shortest(12)"
colors."commit_id prefix".bold = true

# is equivalent to:
[template-aliases]
"format_short_id(id)" = "id.shortest(12)"

[colors]
"commit_id prefix" = { bold = true }

The docs below refer to keys in text using dotted notation, but example blocks will use heading notation to be unambiguous. If you are confident with TOML then use whichever suits you in your config. If you mix dotted keys and headings, you must put the dotted keys before the first heading.

That's probably enough TOML to keep you out of trouble but the syntax guide is very short if you ever need to check.

User settings

[user]
name = "YOUR NAME"
email = "YOUR_EMAIL@example.com"

Don't forget to change these to your own details!

UI settings

Colorizing output

Possible values are always, never, debug and auto (default: auto). auto will use color only when writing to a terminal. debug will print the active labels alongside the regular colorized output.

This setting overrides the NO_COLOR environment variable (if set).

[ui]
color = "never" # Turn off color

Custom colors and styles

You can customize the colors used for various elements of the UI. For example:

[colors]
commit_id = "green"

The following colors are available:

• black
• red
• green
• yellow
• blue
• magenta
• cyan
• white
• default

All of them but "default" come in a bright version too, e.g. "bright red". The "default" color can be used to override a color defined by a parent style (explained below).

You can also use a 6-digit hex code for more control over the exact color used:

[colors]
change_id = "#ff1525"

If you use a string value for a color, as in the examples above, it will be used for the foreground color. You can also set the background color, reverse colors (swap foreground and background), or make the text bold, italic, or underlined. For that, you need to use a table:

[colors]
commit_id = { fg = "green", bg = "#ff1525", bold = true, underline = true }
change_id = { reverse = true, italic = true }

The key names are called "labels". The above used commit_id as label. You can also create rules combining multiple labels. The rules work a bit like CSS selectors. For example, if you want to color commit IDs green in general but make the commit ID of the working-copy commit also be underlined, you can do this:

[colors]
commit_id = "green"
"working_copy commit_id" = { underline = true }

Parts of the style that are not overridden - such as the foreground color in the example above - are inherited from the style of the parent label.

Which elements can be colored is not yet documented, but see the default color configuration for some examples of what's possible.

Default command

When jj is run with no explicit subcommand, the value of the ui.default-command setting will be used instead. Possible values are any valid subcommand name, subcommand alias, or user-defined alias (defaults to "log").

[ui]
default-command = ["log", "--reversed"]

Default description

The editor content of a commit description can be populated by the draft_commit_description template.

[templates]
draft_commit_description = '''
concat(
  coalesce(description, "\n"),
  surround(
    "\nJJ: This commit contains the following changes:\n", "",
    indent("JJ:     ", diff.stat(72)),
  ),
  "\nJJ: ignore-rest\n",
  diff.git(),
)
'''

The value of the ui.default-description setting can also be used in order to fill in things like BUG=, TESTED= etc.

[ui]
default-description = "\n\nTESTED=TODO"

Diff colors and styles

In color-words and git diffs, word-level hunks are rendered with underline. You can override the default style with the following keys:

[colors]
# Highlight hunks with background
"diff removed token" = { bg = "#221111", underline = false }
"diff added token" = { bg = "#002200", underline = false }
# Alternatively, swap colors
"diff token" = { reverse = true, underline = false }

Diff format

[ui]
# Possible values: "color-words" (default), "git", "summary"
diff.format = "git"

Color-words diff options

In color-words diffs, changed words are displayed inline by default. Because it's difficult to read a diff line with many removed/added words, there's a threshold to switch to traditional separate-line format. You can also change the default number of lines of context shown.

• max-inline-alternation: Maximum number of removed/added word alternation to inline. For example, <added> ... <added> sequence has 1 alternation, so the line will be inline if max-inline-alternation >= 1. <added> ... <removed> ... <added> sequence has 3 alternation.

  • 0: disable inlining, making --color-words more similar to --git
  • 1: inline removes-only or adds-only lines
  • 2, 3, ..: inline up to 2, 3, .. alternation
  • -1: inline all lines

  The default is 3.

  This parameter is experimental. The definition is subject to change.

• context: Number of lines of context to show in the diff. The default is 3.

[diff.color-words]
max-inline-alternation = 3
context = 3

Git diff options

In git diffs you can change the default number of lines of context shown.

• context: Number of lines of context to show in the diff. The default is 3.

[diff.git]
context = 3

Generating diffs by external command

If ui.diff.tool is set, the specified diff command will be called instead of the internal diff function.

[ui]
# Use Difftastic by default
diff.tool = ["difft", "--color=always", "$left", "$right"]
# Use tool named "<name>" (see below)
diff.tool = "<name>"

The external diff tool can also be enabled by diff --tool <name> argument. For the tool named <name>, command arguments can be configured as follows.

[merge-tools.<name>]
# program = "<name>"  # Defaults to the name of the tool if not specified
diff-args = ["--color=always", "$left", "$right"]

• $left and $right are replaced with the paths to the left and right directories to diff respectively.

By default jj will invoke external tools with a directory containing the left and right sides. The diff-invocation-mode config can change this to file by file invocations as follows:

[ui]
diff.tool = "vimdiff"

[merge-tools.vimdiff]
diff-invocation-mode = "file-by-file"

By default jj will display a warning when the command exits with a non-success error code. The diff-expected-exit-codes config can suppress this warning message for specific exit codes:

[merge-tools.delta]
diff-expected-exit-codes = [0, 1]

Conflict marker style

You can configure which style of conflict markers to use when materializing conflicts:

[ui]
# Shows a single snapshot and one or more diffs to apply to it
conflict-marker-style = "diff"
# Shows a snapshot for each side and base of the conflict
conflict-marker-style = "snapshot"
# Uses Git's "diff3" conflict markers to support tools that depend on it
conflict-marker-style = "git"

For more details about these conflict marker styles, see the conflicts page.

Set of immutable commits

You can configure the set of immutable commits via revset-aliases."immutable_heads()". The default set of immutable heads is builtin_immutable_heads(), which in turn is defined as present(trunk()) | tags() | untracked_remote_bookmarks(). For example, to also consider the release@origin bookmark immutable:

[revset-aliases]
"immutable_heads()" = "builtin_immutable_heads() | release@origin"

To prevent rewriting commits authored by other users:

# The `trunk().. &` bit is an optimization to scan for non-`mine()` commits
# only among commits that are not in `trunk()`.
[revset-aliases]
"immutable_heads()" = "builtin_immutable_heads() | (trunk().. & ~mine())"

Ancestors of the configured set are also immutable. The root commit is always immutable even if the set is empty.

Immutable commits (other than the root commit) can be rewritten using the --ignore-immutable CLI flag.

!!! warning

Using `--ignore-immutable` will allow you to rewrite any commit in the
history, and all descendants, without warning. Use this power wisely, and
remember `jj undo`.

Behavior of prev and next commands

If you prefer using an "edit-based" workflow, rather than squashing modifications into parent changes, you may find yourself using the prev and next commands with their --edit flag often to move between your changes. You can avoid having to type the --edit flag every time you need it by actually making it the default:

[ui.movement]
edit = true

You can pass the --no-edit flag to prev and next if you find yourself needing the original behavior.

List

Default Template

You can configure the template used when no -T is specified.

• templates.config_list for jj config list

[templates]
# Use builtin config list template
config_list = "builtin_config_list"

If you want to see the config variable origin (type and path) when you do jj config list you can add this to your config:

[templates]
config_list = "builtin_config_list_detailed"

Log

Default revisions

You can configure the revisions jj log would show when neither -r nor any paths are specified.

[revsets]
# Show commits that are not in `main@origin`
log = "main@origin.."

The default value for revsets.log is 'present(@) | ancestors(immutable_heads().., 2) | present(trunk())'.

Default Template

You can configure the template used when no -T is specified.

• templates.log for jj log
• templates.op_log for jj op log
• templates.show for jj show

[templates]
# Use builtin log template
log = "builtin_log_compact"
# Use builtin op log template
op_log = "builtin_op_log_compact"
# Use builtin show template
show = "builtin_log_detailed"

If you want to see the full description when you do jj log you can add this to your config:

[templates]
log = "builtin_log_compact_full_description"

Graph style

[ui]
# Possible values: "curved" (default), "square", "ascii", "ascii-large"
graph.style = "square"

Node style

The symbols used to represent commits or operations can be customized via templates.

• templates.log_node for commits (with Option<Commit> keywords)
• templates.op_log_node for operations (with Operation keywords)

For example:

[templates]
log_node = '''
coalesce(
  if(!self, "🮀"),
  if(current_working_copy, "@"),
  if(root, "┴"),
  if(immutable, "●", "○"),
)
'''
op_log_node = 'if(current_operation, "@", "○")'

Wrap log content

If enabled, log/evolog/op log content will be wrapped based on the terminal width.

[ui]
log-word-wrap = true

Display of commit and change ids

Can be customized by the format_short_id() template alias.

[template-aliases]
# Highlight unique prefix and show at least 12 characters (default)
'format_short_id(id)' = 'id.shortest(12)'
# Just the shortest possible unique prefix
'format_short_id(id)' = 'id.shortest()'
# Show unique prefix and the rest surrounded by brackets
'format_short_id(id)' = 'id.shortest(12).prefix() ++ "[" ++ id.shortest(12).rest() ++ "]"'
# Always show 12 characters
'format_short_id(id)' = 'id.short(12)'

To customize these separately, use the format_short_commit_id() and format_short_change_id() aliases:

[template-aliases]
# Uppercase change ids. `jj` treats change and commit ids as case-insensitive.