docs/templates.md
Jujutsu supports a functional language to customize output of commands. The language consists of literals, keywords, operators, functions, and methods.
A couple of jj commands accept a template via -T/--template option.
Keywords represent objects of different types; the types are described in
a follow-up section. In addition to context-specific keywords, the top-level
object can be referenced as self.
In jj log templates, all 0-argument methods of the Commit
type are available as keywords. For example, commit_id is
equivalent to self.commit_id().
In jj op log templates, all 0-argument methods of the Operation
type are available as keywords. For example,
current_operation is equivalent to self.current_operation().
The following operators are supported. x and y below can be any expression.
Operators are listed in order of binding power from strongest to weakest, e.g.
x ++ y * z is interpreted as x ++ (y * z) since * has stronger binding
power than ++. Infix operators of the same binding power are parsed from left
to right, e.g. x * y / z is interpreted as (x * y) / z.
As seen above, parentheses can be used to control evaluation order, e.g. (x + y) * z.
x.f(): Method call.f(x): Function call.-x: Negate integer value.!x: Logical not.p:x: String pattern or pattern alias named p.x * y, x / y, x % y: Multiplication/division/remainder. Operands must
be Integers.x + y, x - y: Addition/subtraction. Operands must be Integers.x >= y, x > y, x <= y, x < y: Greater than or equal/greater than/
lesser than or equal/lesser than. Operands must be Integers.x == y, x != y: Equal/not equal. Operands must be either Boolean,
Integer, or String.x && y: Logical and, short-circuiting.x || y: Logical or, short-circuiting.x ++ y: Concatenate x and y templates.The following functions are defined.
fill(width: Integer, content: Template) -> Template: Fill lines at
the given width.indent(prefix: Template, content: Template) -> Template: Indent
non-empty lines by the given prefix.pad_start(width: Integer, content: Template, [fill_char: Template]): Pad (or
right-justify) content by adding leading fill characters. The content
shouldn't have newline character.pad_end(width: Integer, content: Template, [fill_char: Template]): Pad (or
left-justify) content by adding trailing fill characters. The content
shouldn't have newline character.pad_centered(width: Integer, content: Template, [fill_char: Template]): Pad
content by adding both leading and trailing fill characters. If an odd number
of fill characters are needed, the trailing fill will be one longer than the
leading fill. The content shouldn't have newline characters.truncate_start(width: Integer, content: Template, [ellipsis: Template]):
Truncate content by removing leading characters. The content shouldn't
have newline character. If ellipsis is provided and content was truncated,
prepend the ellipsis to the result.truncate_end(width: Integer, content: Template, [ellipsis: Template]):
Truncate content by removing trailing characters. The content shouldn't
have newline character. If ellipsis is provided and content was truncated,
append the ellipsis to the result.hash(content: Stringify) -> String:
Hash the input and return a hexadecimal string representation of the digest.label(label: Stringify, content: Template) -> Template: Apply a custom
color label to the content. The label is evaluated as a
space-separated string.hyperlink(url: Stringify, text: Template, [fallback: Template]) -> Template:
Render text as a hyperlink to url using OSC 8 escape sequences
when outputting with color enabled. Otherwise, renders fallback instead,
which defaults to text. Use --color=always to force hyperlinks when piping
output to a terminal emulator that supports OSC 8.raw_escape_sequence(content: Template) -> Template: Preserves any escape
sequences in content (i.e., bypasses sanitization) and strips labels.
Note: This function is intended for escape sequences and as such, its output
is expected to be invisible / of no display width. Outputting content with
nonzero display width may break wrapping, indentation etc.stringify(content: Stringify) -> String: Format content to string. This
effectively removes color labels.json(value: Serialize) -> String: Serialize value in JSON format.if(condition: Boolean, then: Any, [else: Any]) -> Any:
Conditionally evaluates to then/else content.coalesce(content: Template...) -> Template: Returns the first non-empty
content.concat(content: Template...) -> Template:
Same as content_1 ++ ... ++ content_n.join(separator: Template, content: Template...) -> Template: Insert
separator between contents.separate(separator: Template, content: Template...) -> Template: Insert
separator between non-empty contents.surround(prefix: Template, suffix: Template, content: Template) -> Template:
Surround non-empty content with texts such as parentheses.config(name: Stringify) -> Option<ConfigValue>: Look up configuration
value by name.git_web_url([remote: String]) -> String: Best-effort conversion of a git
remote URL to an HTTPS web URL. Defaults to the "origin" remote. Returns an
empty string on failure. SSH host alias resolution is currently unsupported.AnnotationLine typeConversion: Boolean: no, Serialize: no, Template: no
The following methods are defined.
.commit() -> Commit: Commit responsible for changing the relevant line..content() -> Template: Line content including newline character..line_number() -> Integer: 1-based line number..original_line_number() -> Integer: 1-based line number in the original commit..first_line_in_hunk() -> Boolean: False when the directly preceding line
references the same commit.Any typeConversion: Boolean: no, Serialize: maybe, Template: maybe
All types can be implicitly converted to Any. No methods are defined.
AnyList typeConversion: Boolean: no, Serialize: maybe, Template: maybe
The following methods are defined.
.join(separator: Template) -> Template: Concatenate elements with
the given separator.Boolean typeConversion: Boolean: yes, Serialize: yes, Template: yes
No methods are defined. Can be constructed with false or true literal.
ChangeId typeConversion: Boolean: no, Serialize: yes, Template: yes
The following methods are defined.
.normal_hex() -> String: Normal hex representation (0-9a-f) instead of the
canonical "reversed" (z-k) representation..short([len: Integer]) -> String.shortest([min_len: Integer]) -> ShortestIdPrefix: Shortest unique prefix.Commit typeConversion: Boolean: no, Serialize: yes, Template: no
This type cannot be printed. The following methods are defined.
.description() -> String: Usually ends with a trailing \n, if non-blank..trailers() -> List<Trailer>: The trailers at the end of the commit
description that are formatted as <key>: <value>. These are returned in the
same order as they appear in the description, and there may be multiple
Trailers with the same key..change_id() -> ChangeId.commit_id() -> CommitId.parents() -> List<Commit>.author() -> Signature.committer() -> Signature.signature() -> Option<CryptographicSignature>: Cryptographic signature if
the commit was signed..mine() -> Boolean: Commits where the author's email matches the email of
the current user..working_copies() -> List<WorkspaceRef>: For multi-workspace repositories,
returns a list of workspace references for each workspace whose working-copy
commit matches the current commit..current_working_copy() -> Boolean: True for the working-copy commit of the
current workspace..bookmarks() -> List<CommitRef>: Local and remote bookmarks pointing to the
commit. A tracked remote bookmark will be included only if its target is
different from the local one..local_bookmarks() -> List<CommitRef>: All local bookmarks pointing to the
commit..remote_bookmarks() -> List<CommitRef>: All remote bookmarks pointing to the
commit..tags() -> List<CommitRef>: Local and remote tags pointing to the commit. A
tracked remote tag will be included only if its target is different from the
local one..local_tags() -> List<CommitRef>: All local tags pointing to the commit..remote_tags() -> List<CommitRef>: All remote tags pointing to the commit..divergent() -> Boolean: True if the commit's change ID corresponds to multiple
visible commits..hidden() -> Boolean: True if the commit is not visible (a.k.a. abandoned)..change_offset() -> Option<Integer>: The change offset
of this commit. May not be available for some commits..immutable() -> Boolean: True if the commit is included in the set of
immutable commits..contained_in(revset: StringLiteral) -> Boolean: True if the commit is included in
the provided revset..conflict() -> Boolean: True if the commit contains merge conflicts..empty() -> Boolean: True if the commit modifies no files..diff([files: StringLiteral]) -> TreeDiff: Changes from the parents within the
files expression. All files are compared by default, but it is
likely to change in future version to respect the command line path arguments..files([files: StringLiteral]) -> List<TreeEntry>: Files that exist in this commit,
matching the files expression. Use .diff().files() to list
changed files..conflicted_files() -> List<TreeEntry>: Conflicted files in this commit..root() -> Boolean: True if the commit is the root commit.CommitEvolutionEntry typeConversion: Boolean: no, Serialize: yes, Template: no
This type cannot be printed. The following methods are defined.
.commit() -> Commit: New commit..operation() -> Operation: Operation where the commit was created or
rewritten..predecessors() -> List<Commit>: Predecessor commits of this entry..inter_diff([files: StringLiteral]) -> TreeDiff: Changes between this commit and its
predecessor version(s), rebased onto the parents of this commit to avoid unrelated
changes (similar to jj evolog -p).CommitId typeConversion: Boolean: no, Serialize: yes, Template: yes
The following methods are defined.
.short([len: Integer]) -> String.shortest([min_len: Integer]) -> ShortestIdPrefix: Shortest unique prefix.CommitRef typeConversion: Boolean: no, Serialize: yes, Template: yes
The following methods are defined.
.name() -> RefSymbol: Local bookmark or tag name..remote() -> Option<RefSymbol>: Remote name if this is a remote ref..present() -> Boolean: True if the ref points to any commit..conflict() -> Boolean: True if the bookmark or tag is
conflicted..normal_target() -> Option<Commit>: Target commit if the ref is not
conflicted and points to a commit..removed_targets() -> List<Commit>: Old target commits if conflicted..added_targets() -> List<Commit>: New target commits. The list usually
contains one "normal" target..tracked() -> Boolean: True if the ref is tracked by a local ref. The local
ref might have been deleted (but not pushed yet.).tracking_present() -> Boolean: True if the ref is tracked by a local ref,
and if the local ref points to any commit..tracking_ahead_count() -> SizeHint: Number of commits ahead of the tracking
local ref..tracking_behind_count() -> SizeHint: Number of commits behind of the
tracking local ref..synced() -> Boolean: For a local bookmark, true if synced with all tracked
remotes. For a remote bookmark, true if synced with the tracking local
bookmark.ConfigValue typeConversion: Boolean: no, Serialize: yes, Template: yes
This type can be printed in TOML syntax. The following methods are defined.
.as_boolean() -> Boolean: Extract boolean..as_integer() -> Integer: Extract integer..as_string() -> String: Extract string. This does not convert non-string
value (e.g. integer) to string..as_string_list() -> List<String>: Extract list of strings.CryptographicSignature typeConversion: Boolean: no, Serialize: no, Template: no
The following methods are defined.
.status() -> String: The signature's status ("good", "bad", "unknown",
"invalid")..key() -> String: The signature's key id representation (for GPG and SSH,
this is the public key fingerprint)..display() -> String: The signature's display string (for GPG, this is the
formatted primary user ID; for SSH, this is the principal).!!! warning
Calling any of `.status()`, `.key()`, or `.display()` is slow, as it incurs
the performance cost of verifying the signature (for example shelling out
to `gpg` or `ssh-keygen`). Though consecutive calls will be faster, because
the backend caches the verification result.
!!! info
As opposed to calling any of `.status()`, `.key()`, or `.display()`,
checking for signature presence through boolean coercion is fast:
```
if(commit.signature(), "commit has a signature", "commit is unsigned")
```
DiffStatEntry typeConversion: Boolean: no, Serialize: no, Template: no
This type holds the diff stats per file. The following methods are defined.
.bytes_delta() -> Integer: The difference in size of the file, in bytes..lines_added() -> Integer: Number of lines added..lines_removed() -> Integer: Number of lines deleted..path() -> RepoPath: Path to the entry. If the entry is a copy/rename, this
points to the target (or right) entry..display_diff_path() -> String: Format path for display, taking into account copy/rename information..status() -> String: One of "modified", "added", "removed", "copied", or "renamed"..status_char() -> String: One of "M" (modified), "A" (added), "D" (removed),
"C" (copied), or "R" (renamed).DiffStats typeConversion: Boolean: no, Serialize: no, Template: yes
This type can be printed as a histogram of the changes. The following methods are defined.
.files() -> List<DiffStatEntry>: Per-file stats for changed files..total_added() -> Integer: Total number of insertions..total_removed() -> Integer: Total number of deletions.Email typeConversion: Boolean: yes, Serialize: yes, Template: yes
The email field of a signature may or may not look like an email address. It may
be empty, may not contain the symbol @, and could in principle contain
multiple @s.
The following methods are defined.
.local() -> String: the part of the email before the first @, usually the
username..domain() -> String: the part of the email after the first @ or the empty
string.Integer typeConversion: Boolean: no, Serialize: yes, Template: yes
No methods are defined.
List typeConversion: Boolean: yes, Serialize: maybe, Template: maybe
A list can be implicitly converted to Boolean. The following methods are
defined.
.len() -> Integer: Number of elements in the list..join(separator: Template) -> Template: Concatenate elements with
the given separator..filter(|item| expression) -> List: Filter list elements by predicate
expression. Example: description.lines().filter(|s| s.contains("#")).map(|item| expression) -> AnyList: Apply template expression
to each element. Example: parents.map(|c| c.commit_id().short()).any(|item| expression) -> Boolean: Returns true if any element satisfies
the predicate expression. Example: parents.any(|c| c.description().contains("fix")).all(|item| expression) -> Boolean: Returns true if all elements satisfy
the predicate expression. Example: parents.all(|c| c.mine()).first() -> T: Returns the first element. Errors if the list is empty..last() -> T: Returns the last element. Errors if the list is empty..get(index: Integer) -> T: Returns the element at index (0-based). Errors
if the index is out of bounds..reverse() -> List: Returns the list in reverse order..skip(count: Integer) -> List: Skips the first count elements and
returns the rest..take(count: Integer) -> List: Returns only the first count elements.List<Trailer> typeThe following methods are defined. See also the List type.
.contains_key(key: Stringify) -> Boolean: True if the commit description
contains at least one trailer with the key key.Operation typeConversion: Boolean: no, Serialize: yes, Template: no
This type cannot be printed. The following methods are defined.
.current_operation() -> Boolean.description() -> String.id() -> OperationId.tags() -> String.time() -> TimestampRange.user() -> String.snapshot() -> Boolean: True if the operation is a snapshot operation..workspace_name() -> String: The name of the workspace the operation was
created from. An empty string if the operation wasn't created from a
workspace..root() -> Boolean: True if the operation is the root operation..parents() -> List<Operation>OperationId typeConversion: Boolean: no, Serialize: yes, Template: yes
The following methods are defined.
.short([len: Integer]) -> StringOption typeConversion: Boolean: yes, Serialize: maybe, Template: maybe
An option can be implicitly converted to Boolean denoting whether the
contained value is set. If set, all methods of the contained value can be
invoked. If not set, an error will be reported inline on method call.
On comparison between two optional values or optional and non-optional values, unset value is not an error. Unset value is considered less than any set values.
RefSymbol typeConversion: Boolean: no, Serialize: yes, Template: yes
A String type, but is formatted as revset symbol by quoting
and escaping if necessary. Unlike strings, this cannot be implicitly converted
to Boolean.
RepoPath typeConversion: Boolean: no, Serialize: yes, Template: yes
A slash-separated path relative to the repository root. The following methods are defined.
.absolute() -> String: Format as absolute path using platform-native
separator..display() -> String: Format path for display. The formatted path uses
platform-native separator, and is relative to the current working directory..parent() -> Option<RepoPath>: Parent directory path.Serialize typeAn expression that can be serialized in machine-readable format such as JSON.
!!! note
Field names and value types in the serialized output are usually stable
across jj versions, but the backward compatibility isn't guaranteed. If the
underlying data model is updated, the serialized output may change.
ShortestIdPrefix typeConversion: Boolean: no, Serialize: yes, Template: yes
The following methods are defined.
.prefix() -> String.rest() -> String.upper() -> ShortestIdPrefix.lower() -> ShortestIdPrefixSignature typeConversion: Boolean: no, Serialize: yes, Template: yes
The following methods are defined.
.name() -> String.email() -> Email.timestamp() -> TimestampSizeHint typeConversion: Boolean: no, Serialize: yes, Template: no
This type cannot be printed. The following methods are defined.
.lower() -> Integer: Lower bound..upper() -> Option<Integer>: Upper bound if known..exact() -> Option<Integer>: Exact value if upper bound is known and it
equals to the lower bound..zero() -> Boolean: True if upper bound is known and is 0. Equivalent to
.upper() == 0.String typeConversion: Boolean: yes, Serialize: yes, Template: yes
A string can be implicitly converted to Boolean. The following methods are
defined.
.len() -> Integer: Length in UTF-8 bytes.
.contains(needle: Stringify) -> Boolean: Whether the string contains the
provided stringifiable value as a substring.
.match(needle: StringPattern) -> String: Extracts
the first matching part of the string for the given pattern.
An empty string is returned if there is no match.
.replace(pattern: StringPattern, replacement: Stringify, [limit: Integer]) -> String:
Replace occurrences of the given pattern with the replacement string.
By default, all occurrences are replaced. If limit is specified, at most
that many occurrences are replaced.
Supports capture groups in patterns using $0 (entire match), $1, $2 etc.
.first_line() -> String
.lines() -> List<String>: Split into lines excluding newline characters.
.split(separator: StringPattern, [limit: Integer]) -> List<String>: Split into
substrings by the given separator pattern. If limit is specified, it
determines the maximum number of elements in the result, with the remainder
of the string returned as the final element. A limit of 0 returns an empty list.
.upper() -> String
.lower() -> String
.starts_with(needle: Stringify) -> Boolean
.ends_with(needle: Stringify) -> Boolean
.remove_prefix(needle: Stringify) -> String: Removes the passed prefix, if
present.
.remove_suffix(needle: Stringify) -> String: Removes the passed suffix, if
present.
.trim() -> String: Removes leading and trailing whitespace
.trim_start() -> String: Removes leading whitespace
.trim_end() -> String: Removes trailing whitespace
.substr(start: Integer, [end: Integer]) -> String: Extract substring. The
start/end indices should be specified in units of UTF-8 bytes. Indices are
0-based and end is exclusive. Negative values count from the end of the
string, with -1 being the last byte. If the start index is in the middle
of a UTF-8 codepoint, the codepoint is fully part of the result. If the end
index is in the middle of a UTF-8 codepoint, the codepoint is not part of the
result. If end is not given, returns from start to the end of the string.
.escape_json() -> String: Serializes the string in JSON format. This
function is useful for making machine-readable templates. For example, you
can use it in a template like '{ "foo": ' ++ foo.escape_json() ++ ' }' to
return a JSON/JSONL.
Stringify typeAn expression that can be converted to a String.
Any types that can be converted to Template can also be Stringify. Unlike
Template, color labels are stripped.
StringLiteral typeA string literal known at parse time. Unlike Stringify, this cannot be a
dynamic expression - it must be a literal value like "main" or "format".
String literals must be surrounded by single or double quotes (' or ").
A double-quoted string literal supports the following escape sequences:
\": double quote\\: backslash\t: horizontal tab\r: carriage return\n: new line\0: null\e: escape (i.e., \x1b)\xHH: byte with hex value HHOther escape sequences are not supported. Any UTF-8 characters are allowed
inside a string literal, with two exceptions: unescaped "-s and uses of \
that don't form a valid escape sequence.
A single-quoted string literal has no escape syntax. ' can't be expressed
inside a single-quoted string literal.
String literals have their own type so that the value can be validated at parse
time. For example, contained_in(revset) requires a literal so the revset can
be parsed and checked before the template is evaluated.
StringPattern typeConversion: Boolean: no, Serialize: no, Template: no
These are the exact same as the String pattern type in revsets, except that quotes are mandatory.
Literal strings may be used, which are interpreted as case-sensitive substring matching.
Currently StringPattern values cannot be passed around as values and may
only occur directly in the call site they are used in.
Template typeConversion: Boolean: no, Serialize: no, Template: yes
Most types can be implicitly converted to Template. No methods are defined.
Timestamp typeConversion: Boolean: no, Serialize: yes, Template: yes
The following methods are defined.
.ago() -> String: Format as relative timestamp..format(format: StringLiteral) -> String: Format with the specified strftime-like
format string..utc() -> Timestamp: Convert timestamp into UTC timezone..local() -> Timestamp: Convert timestamp into local timezone..after(date: StringLiteral) -> Boolean: True if the timestamp is exactly at or
after the given date. Supported date formats are the same as the revset
Date pattern type..before(date: StringLiteral) -> Boolean: True if the timestamp is before, but
not including, the given date. Supported date formats are the same as the
revset Date pattern type..since(start: Timestamp) -> TimestampRange: The TimestampRange between start and
self. It may be used in conjunction with TimestampRange::duration to obtain
a human-friendly duration between two Timestamps.TimestampRange typeConversion: Boolean: no, Serialize: yes, Template: yes
The following methods are defined.
.start() -> Timestamp.end() -> Timestamp.duration() -> StringTrailer typeConversion: Boolean: no, Serialize: no, Template: yes
The following methods are defined.
.key() -> String.value() -> StringTreeDiff typeConversion: Boolean: no, Serialize: no, Template: no
This type cannot be printed. The following methods are defined.
.files() -> List<TreeDiffEntry>: Changed files..color_words([context: Integer]) -> Template: Format as a word-level diff
with changes indicated only by color..git([context: Integer]) -> Template: Format as a Git diff..stat([width: Integer]) -> DiffStats: Calculate stats of changed lines..summary() -> Template: Format as a list of status code and path pairs.TreeDiffEntry typeConversion: Boolean: no, Serialize: no, Template: no
This type cannot be printed. The following methods are defined.
.path() -> RepoPath: Path to the entry. If the entry is a copy/rename, this
points to the target (or right) entry..display_diff_path() -> String: Format path for display, taking into account copy/rename information..status() -> String: One of "modified", "added", "removed",
"copied", or "renamed"..status_char() -> String: Single-character status indicator: "M" for modified,
"A" for added, "D" for removed, "C" for copied, or "R" for renamed..source() -> TreeEntry: The source (or left) entry..target() -> TreeEntry: The target (or right) entry.TreeEntry typeConversion: Boolean: no, Serialize: no, Template: no
This type cannot be printed. The following methods are defined.
.path() -> RepoPath: Path to the entry..conflict() -> Boolean: True if the entry is a merge conflict..conflict_side_count() -> Integer: Number of sides in the merge conflict (1 if not
conflicted, 2 or more for multi-way merges)..file_type() -> String: One of "file", "symlink", "tree",
"git-submodule", or "conflict"..executable() -> Boolean: True if the entry is an executable file.WorkspaceRef typeConversion: Boolean: no, Serialize: yes, Template: yes
The following methods are defined.
.name() -> RefSymbol: Returns the workspace name as a symbol..target() -> Commit: Returns the working-copy commit of this workspace..root() -> Template: Returns the absolute path to the workspace root.You can customize the output colors by using color labels. jj
adds some labels automatically; they can also be added manually.
Template fragments are usually automatically labeled with the command name,
the context (or the top-level object), and the method names. For example, the
following template is labeled as op_log operation id short automatically:
jj op log -T 'self.id().short()'
The exact names of such labels are often straightforward, but are not currently
documented. You can discover the actual label names used with the
--color=debug option, e.g.
jj op log -T 'self.id().short()' --color=debug
Additionally, you can manually insert arbitrary labels using the
label(label, content) function. For example,
jj op log -T '"ID: " ++ self.id().short().substr(0, 1) ++ label("id short", "<redacted>")'
will print "ID:" in the default style, and the string <redacted> in the same
style as the first character of the id. It would also be fine to use an
arbitrary template instead of the string "<redacted>", possibly including
nested invocations of label().
You are free to use custom label names as well. This will only have a visible effect if you also customize their colors explicitly.
The default templates and aliases() are defined in the [templates] and
[template-aliases] sections of the config respectively. The exact definitions
can be seen in the cli/src/config/templates.toml file in jj's source
tree.
New keywords, functions, and <name>:<value> patterns can be defined as
aliases, by using any combination of the predefined keywords/functions and other
aliases.
Alias functions can be overloaded by the number of parameters. However, builtin functions will be shadowed by name, and can't co-exist with aliases.
For example:
[template-aliases]
'commit_change_ids' = '''
concat(
format_field("Commit ID", commit_id),
format_field("Change ID", change_id),
)
'''
'format_field(key, value)' = 'key ++ ": " ++ value ++ "\n"'
'json:x' = 'json(x) ++ "\n"'
Get short commit IDs of the working-copy parents:
jj log --no-graph -r @ -T 'parents.map(|c| c.commit_id().short()).join(",")'
Show machine-readable list of full commit and change IDs:
jj log --no-graph -T 'commit_id ++ " " ++ change_id ++ "\n"'
Print the description of the current commit, defaulting to (no description set):
jj log -r @ --no-graph -T 'coalesce(description, "(no description set)\n")'