# Templates
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
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`.
### Commit keywords
In `jj log` templates, all 0-argument methods of [the `Commit`
type](#commit-type) are available as keywords. For example, `commit_id` is
equivalent to `self.commit_id()`.
### Operation keywords
In `jj op log` templates, all 0-argument methods of [the `Operation`
type](#operation-type) are available as keywords. For example,
`current_operation` is equivalent to `self.current_operation()`.
## Operators
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`.
1. * `x.f()`: Method call.
* `f(x)`: Function call.
2. * `-x`: Negate integer value.
* `!x`: Logical not.
3. * `p:x`: String pattern or pattern alias named `p`.
4. * `x * y`, `x / y`, `x % y`: Multiplication / division / remainder. Operands must
be `Integer`s.
5. * `x + y`, `x - y`: Addition / subtraction. Operands must be `Integer`s.
6. * `x >= y`, `x > y`, `x <= y`, `x < y`: Greater than or equal / greater than /
lesser than or equal / lesser than. Operands must be `Integer`s.
7. * `x == y`, `x != y`: Equal / not equal. Operands must be either `Boolean`,
`ByteString`, `Integer`, or `String`.
8. * `x && y`: Logical and, short-circuiting.
9. * `x || y`: Logical or, short-circuiting.
10. * `x ++ y`: Concatenate `x` and `y` templates.
## Global functions
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](#color-labels) 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](https://github.com/Alhadis/OSC8-Adoption)
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.
* `replace(pattern: StringPattern, content: Template, replacement: |RegexCaptures| -> Template) -> Template`:
Replace every match of `pattern` in `content` by formatting the `replacement`
lambda for each match.
This is similar to [`String.replace()`](#string-type), but operates on
`Template` content and preserves formatting of the parts of `content` that are
not replaced. The replacement itself is newly formatted template content.
The lambda argument is a [`RegexCaptures`](#regexcaptures-type) value for the
current match. Use `.get(index)` to access capture groups by index, `.name(name)`
to access named capture groups, and `.len()` to get the number of captures
including capture group 0 for the full match.
* `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 `content`s.
* `separate(separator: Template, content: Template...) -> Template`: Insert
`separator` between **non-empty** `content`s.
* `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.
## Types
### `AnnotationLine` type
_Conversion: `Boolean`: no, `Serialize`: no, `Template`: no_
The following methods are defined.
* `.commit() -> Commit`: Commit responsible for changing the relevant line.
* `.content() -> ByteString`: 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` type
_Conversion: `Boolean`: no, `Serialize`: maybe, `Template`: maybe_
All types can be implicitly converted to `Any`. No methods are defined.
### `AnyList` type
_Conversion: `Boolean`: no, `Serialize`: maybe, `Template`: maybe_
The following methods are defined.
* `.join(separator: Template) -> Template`: Concatenate elements with
the given `separator`.
### `Boolean` type
_Conversion: `Boolean`: yes, `Serialize`: yes, `Template`: yes_
No methods are defined. Can be constructed with `false` or `true` literal.
### `ByteString` type
_Conversion: `Boolean`: yes, `Serialize`: yes, `Template`: yes_
A byte string, whose encoding is considered ASCII-compatible (e.g. UTF-8), but
isn't guaranteed. This can be implicitly converted to `Boolean`. The following
methods are defined.
* `.len() -> Integer`: Length in bytes.
* `.contains(needle: ByteStringify) -> Boolean`: Whether the string contains the
provided stringifiable value as a substring.
* `.match(needle: StringPattern) -> ByteString`: Extract the first matching part
of the string for the given pattern.
An empty string is returned if there is no match.
* `.starts_with(needle: ByteStringify) -> Boolean`: Whether `needle` is a
prefix of the string.
* `.ends_with(needle: ByteStringify) -> Boolean`: Whether `needle` is a suffix
of the string.
* `.remove_prefix(needle: ByteStringify) -> ByteString`: Remove the passed
prefix, if present.
* `.remove_suffix(needle: ByteStringify) -> ByteString`: Remove the passed
suffix, if present.
* `.trim() -> ByteString`: Remove leading and trailing ASCII whitespace.
* `.trim_start() -> ByteString`: Remove leading ASCII whitespace.
* `.trim_end() -> ByteString`: Remove trailing ASCII whitespace.
* `.substr(start: Integer, [end: Integer]) -> ByteString`: Extract substring.
Indices are 0-based and `end` is exclusive. Negative values count from the end
of the string, with `-1` being the last byte. If `end` is not given, returns
from `start` to the end of the string.
* `.first_line() -> ByteString`
* `.lines() -> List<ByteString>`: Split into lines excluding newline characters.
* `.split(separator: StringPattern, [limit: Integer]) -> List<ByteString>`:
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.
* `.replace(pattern: StringPattern, replacement: ByteStringify, [limit:
Integer]) -> ByteString`: 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.
* `.upper() -> ByteString`: Map each ASCII character to upper case.
* `.lower() -> ByteString`: Map each ASCII character to lower case.
### `ByteStringify` type
An expression that can be converted to a `ByteString`.
A `String` can be converted to a `ByteString` losslessly. Any types that can be
converted to `Template` can also be `ByteStringify`. Unlike `Template`, color
labels are stripped.
### `ChangeId` type
_Conversion: `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` type
_Conversion: `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
`Trailer`s 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](glossary.md#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](config.md#set-of-immutable-commits).
* `.contained_in(revset: StringLiteral) -> Boolean`: True if the commit is included in
[the provided revset](revsets.md).
* `.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](filesets.md). 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](filesets.md). 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` type
_Conversion: `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` type
_Conversion: `Boolean`: no, `Serialize`: yes, `Template`: yes_
The following methods are defined.
* `.short([len: Integer]) -> String`
* `.shortest([min_len: Integer]) -> ShortestIdPrefix`: Shortest unique prefix.
### `CommitRef` type
_Conversion: `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](bookmarks.md#conflicts).
* `.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` type
_Conversion: `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` type
_Conversion: `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` type
_Conversion: `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` type
_Conversion: `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` type
_Conversion: `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` type
_Conversion: `Boolean`: no, `Serialize`: yes, `Template`: yes_
No methods are defined.
### `List` type
_Conversion: `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>` type
The 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` type
_Conversion: `Boolean`: no, `Serialize`: yes, `Template`: no_
This type cannot be printed. The following methods are defined.
* `.current_operation() -> Boolean`
* `.description() -> String`
* `.id() -> OperationId`
* `.attributes() -> 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` type
_Conversion: `Boolean`: no, `Serialize`: yes, `Template`: yes_
The following methods are defined.
* `.short([len: Integer]) -> String`
### `Option` type
_Conversion: `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` type
_Conversion: `Boolean`: no, `Serialize`: yes, `Template`: yes_
[A `String` type](#string-type), but is formatted as revset symbol by quoting
and escaping if necessary. Unlike strings, this cannot be implicitly converted
to `Boolean`.
### `RegexCaptures` type
_Conversion: `Boolean`: no, `Serialize`: no, `Template`: no_
This type is passed to the replacement lambda of the global
[`replace()`](#global-functions) function.
The following methods are defined.
* `.len() -> Integer`: Number of capture groups, including capture group 0 for
the full match.
* `.get(index: Integer) -> ByteString`: Returns the capture group at `index`.
Capture group 0 is the full match. Errors if the index is out of bounds.
* `.name(name: Stringify) -> ByteString`: Returns the named capture group
`name`. Errors if there is no such named capture group.
### `RepoPath` type
_Conversion: `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` type
An 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` type
_Conversion: `Boolean`: no, `Serialize`: yes, `Template`: yes_
The following methods are defined.
* `.prefix() -> String`
* `.rest() -> String`
* `.upper() -> ShortestIdPrefix`
* `.lower() -> ShortestIdPrefix`
### `Signature` type
_Conversion: `Boolean`: no, `Serialize`: yes, `Template`: yes_
The following methods are defined.
* `.name() -> String`
* `.email() -> Email`
* `.timestamp() -> Timestamp`
### `SizeHint` type
_Conversion: `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` type
_Conversion: `Boolean`: yes, `Serialize`: yes, `Template`: yes_
A UTF-8-encoded string. This 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.
* `.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.
* `.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.
* `.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.
* `.upper() -> String`
* `.lower() -> 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` type
An 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. Invalid UTF-8 sequences are rejected.
### `StringLiteral` type
A 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 `HH`
Other 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` type
_Conversion: `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.
[String pattern type]: revsets.md#string-patterns
### `Template` type
_Conversion: `Boolean`: no, `Serialize`: no, `Template`: yes_
Most types can be implicitly converted to `Template`. No methods are defined.
### `Timestamp` type
_Conversion: `Boolean`: no, `Serialize`: yes, `Template`: yes_
The following methods are defined.
* `.ago() -> String`: Format as relative timestamp.
* `.format(format: Stringify) -> String`: Format with [the specified strftime-like
format string](https://docs.rs/chrono/latest/chrono/format/strftime/).
* `.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 `Timestamp`s.
[Date pattern type]: revsets.md#date-patterns
### `TimestampRange` type
_Conversion: `Boolean`: no, `Serialize`: yes, `Template`: yes_
The following methods are defined.
* `.start() -> Timestamp`
* `.end() -> Timestamp`
* `.duration() -> String`
### `Trailer` type
_Conversion: `Boolean`: no, `Serialize`: no, `Template`: yes_
The following methods are defined.
* `.key() -> String`
* `.value() -> String`
### `TreeDiff` type
_Conversion: `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` type
_Conversion: `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` type
_Conversion: `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` type
_Conversion: `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.
## Color labels
You can [customize the output colors][config-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:
```sh
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.
```sh
jj op log -T 'self.id().short()' --color=debug
```
Additionally, you can **manually** insert arbitrary labels using the
`label(label, content)` function. For example,
```sh
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][config-colors] explicitly.
[config-colors]: config.md#custom-colors-and-styles
## Configuration
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`][1] file in jj's source
tree.
[1]: https://github.com/jj-vcs/jj/blob/main/cli/src/config/templates.toml
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:
```toml
[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"'
```
## Examples
Get short commit IDs of the working-copy parents:
```sh
Show machine-readable list of full commit and change IDs:
```sh
jj log -G -T 'commit_id ++ " " ++ change_id ++ "\n"'
```
Print the description of the current commit, defaulting to `(no description set)`:
```sh
jj log -G -r @ -T 'coalesce(description, "(no description set)\n")'
```