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, or found with jj config path --repo. For security reasons, they are not located inside the repo.

• The workspace settings. These can be edited with jj config edit --workspace, or found with jj config path --workspace. For security reasons, they are not located inside the workspace.

• Settings specified on 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.

Escapes in strings

There are two (or four) types of strings in TOML: basic and literal, with multi-line versions of each. Basic strings use double quotes (") and support escape sequences, such as "\n", "\"", "\\", etc. Literal strings use single quotes (') and do not support escape sequences. Using 3 double quotes or 3 single quotes to wrap a string makes it multi-line, and then you can use an unescaped double quote or single quote respectively without ending the string.

A string in your config may be interpreted twice, first by the TOML parser and then by a Jujutsu parser. To avoid putting strings in your config that the TOML parser processes before it gets to the Jujutsu parser, you may want to use literal strings or literal multi-line strings in your config.toml files. For example:

[template-aliases]
# basic_template = "'hello' ++ \"\n\""
literal_template = '"hello" ++ "\n"'

basic_template is actually equivalent to this string:

'hello' ++ "
"

because the TOML parser interprets the \n character as part of the string. This causes the Jujutsu parser to receive a different string than what you literally see in the TOML file, which may result in seemingly confusing parse error messages (such as referencing a line that you think shouldn't exist).

On the other hand, literal_template is equivalent to:

"hello" ++ "\n"

because the TOML parser does not escape anything in the literal string.

The same rules of basic and literal strings apply to custom Jujutsu languages: double quotes (") allow escapes whereas single quotes (') do not. So template-aliases.my_template = "'hello\\n'" would probably not be what you want.

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"

jj also supports colors from the ANSI 256-color palette as ansi-color-<N>, where <N> is a number between 0 and 255:

[colors]
commit_id = "ansi-color-81"

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, dim, italic, underlined, or crossed-out. For that, you need to use a table:

[colors]
commit_id = { fg = "green", bg = "#ff1525", bold = true, underline = true }
change_id = { reverse = true, dim = false, 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. self is a Commit object.

[templates]
draft_commit_description = '''
concat(
  builtin_draft_commit_description,
  "\nJJ: ignore-rest\n",
  diff.git(),
)
'''

You can override only the default_commit_description value if you like, e.g.:

[template-aliases]
default_commit_description = '''
"

Closes #NNNN
"
'''

Duplicate commit description

By default, jj duplicate copies the descriptions from the original commits. You can customize this behavior by specifying the duplicate_description template, which is given a Commit object of the original commit.

[templates]
duplicate_description = '''
concat(
  description.trim_end(),
  "\n\n(cherry picked from commit ",
  commit_id,
  ")\n"
)
'''

Note that description usually ends with a \n if it is not blank. Use .trim_end() to remove the \n.

New commit description

When jj new creates a commit without an explicit -m message, it evaluates the new_description template to populate the description. By default, this template is empty.

You can customize this to automatically generate descriptions for new commits. For example, to auto-generate merge commit messages:

[templates]
new_description = '''
if(parents.len() > 1,
  "Merge " ++ parents.skip(1).map(|p| try(
    p.bookmarks().first().name(),
    p.change_id().shortest(8)
  )).join(", ") ++ " into " ++ try(
    parents.first().bookmarks().first().name(),
    parents.first().change_id().shortest(8)
  ) ++ "\n",
  ""
)
'''

Bookmark / tag listing order

By default, jj bookmark list and jj tag list display bookmarks and tags sorted alphabetically by name. You can customize this sorting behavior by specifying sort keys in your config file:

[ui]
bookmark-list-sort-keys = ["name"]
tag-list-sort-keys = ["name"]

The configuration works identically to using the --sort option. The following sort keys are supported: name, author-name, author-email, author-date, committer-name, committer-email, committer-date. Suffix the key with - to sort in descending order. Multiple keys can be supplied here, the first key is the most significant.

When the --sort option is used, the configuration is ignored.

Bookmark advance default targets

The jj bookmark advance command moves bookmarks forward in the graph. The default values for what bookmarks to advance and where to advance them to are:

[revsets]
bookmark-advance-from = 'heads(::to & bookmarks())'  # The closest bookmarks
bookmark-advance-to = '@'  # To the current working copy

The default from is likely to be a good fit for almost everyone. The from revset has access to to, allowing it to find bookmarks relative to the destination revision.

The default to is largely up to your preference and workflow. One simple alternative which fits squash-heavy workflows is @-, while a more involved and versatile alternative that advances to the closest "pushable" revision is:

[revsets]
bookmark-advance-to = 'closest_pushable(@)'

[revset-aliases]
# Closest revision that is mutable, described and either non-empty or a merge
'closest_pushable(to)' = '''
  heads(::to & mutable() & ~description(exact:"") & (~empty() | merges()))
'''

Commit trailers

You can configure automatic addition of one or more trailers to commit descriptions using the commit_trailers template.

Each line of the template is an individual trailer, usually in Key: Value format.

Trailers defined in this template are deduplicated with the existing description: if the entire line of a trailer is already present, it will not be added again. To deduplicate based only on the trailer key, use the trailers.contains_key(key) method within the template.

[templates]
commit_trailers = '''
format_signed_off_by_trailer(self)
++ if(!trailers.contains_key("Change-Id"), format_gerrit_change_id_trailer(self))'''

Some ready-to-use trailer templates are available for frequently used trailers:

• format_signed_off_by_trailer(commit) creates a "Signed-off-by" trailer using the committer info.
• format_gerrit_change_id_trailer(commit) creates a "Change-Id" trailer suitable to be used with Gerrit. It is based Jujutsu's change id.

Existing trailers are also accessible via commit.trailers().

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 }

In color-words diffs, line numbers of context lines are rendered with decreased intensity to highlight changed lines. You can also decrease intensity of context contents.

[colors]
# Dim context line numbers (default)
"diff context line_number" = { dim = true }
# Dim context line numbers and contents (applies to color-words and git diffs)
"diff context" = { dim = true }

Colors and styles can be configured differently for each diff format:

[colors]
# Dim unchanged parts of changed lines in color-words diffs
"diff color_words removed" = { dim = true }
"diff color_words added" = { dim = true }
"diff color_words removed token" = { dim = false }
"diff color_words added token" = { dim = false }

Diff format

[ui]
# Builtin formats: ":color-words" (default), ":git",
#                  ":summary", ":stat", ":types", ":name-only"
# or external command name and arguments (see below)
diff-formatter = ":git"

Color-words diff options

In color-words diffs, changed words are displayed inline by default when color is enabled. When the formatter cannot emit color, changed words are always shown on separate lines because inline changes would not be distinguishable.

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 in colorized output. 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.

• conflict: How conflicts are processed and displayed.

  • "materialize": compare materialized contents (default)
  • "pair": compare individual pairs

  This parameter is experimental.

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

• show-path-prefix: Whether to show the a/ and b/ path prefixes in diff --git output. The default is true.

[diff.git]
context = 3
show-path-prefix = true

Diff stat options

When using a subcommand that displays the diff stat menu like jj show --stat, the bar portion that renders as ++-- can be limited to a maximum width in characters.

[diff.stat]
max-bar-width = 10

By default without this option set, the bar width is unbounded and will use the remaining available space, with a minimum of 30% of the total width.