ilyagr.bsky.social
just playing with tangled
1# Templates
2
3Jujutsu supports a functional language to customize output of commands.
4The language consists of literals, keywords, operators, functions, and
5methods.
6
7A couple of `jj` commands accept a template via `-T`/`--template` option.
8
9## Keywords
10
11Keywords represent objects of different types; the types are described in
12a follow-up section. In addition to context-specific keywords, the top-level
13object can be referenced as `self`.
14
15### Commit keywords
16
17In `jj log`/`jj evolog` templates, all 0-argument methods of [the `Commit`
18type](#commit-type) are available as keywords. For example, `commit_id` is
19equivalent to `self.commit_id()`.
20
21### Operation keywords
22
23In `jj op log` templates, all 0-argument methods of [the `Operation`
24type](#operation-type) are available as keywords. For example,
25`current_operation` is equivalent to `self.current_operation()`.
26
27## Operators
28
29The following operators are supported.
30
31* `x.f()`: Method call.
32* `-x`: Negate integer value.
33* `!x`: Logical not.
34* `x >= y`, `x > y`, `x <= y`, `x < y`: Greater than or equal/greater than/
35 lesser than or equal/lesser than. Operands must be `Integer`s.
36* `x == y`, `x != y`: Equal/not equal. Operands must be either `Boolean`,
37 `Integer`, or `String`.
38* `x && y`: Logical and, short-circuiting.
39* `x || y`: Logical or, short-circuiting.
40* `x ++ y`: Concatenate `x` and `y` templates.
41
42(listed in order of binding strengths)
43
44## Global functions
45
46The following functions are defined.
47
48* `fill(width: Integer, content: Template) -> Template`: Fill lines at
49 the given `width`.
50* `indent(prefix: Template, content: Template) -> Template`: Indent
51 non-empty lines by the given `prefix`.
52* `pad_start(width: Integer, content: Template[, fill_char: Template])`: Pad (or
53 right-justify) content by adding leading fill characters. The `content`
54 shouldn't have newline character.
55* `pad_end(width: Integer, content: Template[, fill_char: Template])`: Pad (or
56 left-justify) content by adding trailing fill characters. The `content`
57 shouldn't have newline character.
58* `pad_centered(width: Integer, content: Template[, fill_char: Template])`: Pad
59 content by adding both leading and trailing fill characters. If an odd number
60 of fill characters are needed, the trailing fill will be one longer than the
61 leading fill. The `content` shouldn't have newline characters.
62* `truncate_start(width: Integer, content: Template[, ellipsis: Template])`:
63 Truncate `content` by removing leading characters. The `content` shouldn't
64 have newline character. If `ellipsis` is provided and `content` was truncated,
65 prepend the `ellipsis` to the result.
66* `truncate_end(width: Integer, content: Template[, ellipsis: Template])`:
67 Truncate `content` by removing trailing characters. The `content` shouldn't
68 have newline character. If `ellipsis` is provided and `content` was truncated,
69 append the `ellipsis` to the result.
70* `label(label: Template, content: Template) -> Template`: Apply label to
71 the content. The `label` is evaluated as a space-separated string.
72* `raw_escape_sequence(content: Template) -> Template`: Preserves any escape
73 sequences in `content` (i.e., bypasses sanitization) and strips labels.
74 Note: This function is intended for escape sequences and as such, its output
75 is expected to be invisible / of no display width. Outputting content with
76 nonzero display width may break wrapping, indentation etc.
77* `stringify(content: Template) -> String`: Format `content` to string. This
78 effectively removes color labels.
79* `if(condition: Boolean, then: Template[, else: Template]) -> Template`:
80 Conditionally evaluate `then`/`else` template content.
81* `coalesce(content: Template...) -> Template`: Returns the first **non-empty**
82 content.
83* `concat(content: Template...) -> Template`:
84 Same as `content_1 ++ ... ++ content_n`.
85* `separate(separator: Template, content: Template...) -> Template`:
86 Insert separator between **non-empty** contents.
87* `surround(prefix: Template, suffix: Template, content: Template) -> Template`:
88 Surround **non-empty** content with texts such as parentheses.
89* `config(name: String) -> ConfigValue`: Look up configuration value by `name`.
90
91## Types
92
93### AnnotationLine type
94
95The following methods are defined.
96
97* `.commit() -> Commit`: Commit responsible for changing the relevant line.
98* `.content() -> Template`: Line content including newline character.
99* `.line_number() -> Integer`: 1-based line number.
100* `.first_line_in_hunk() -> Boolean`: False when the directly preceding line
101 references the same commit.
102
103### Boolean type
104
105No methods are defined. Can be constructed with `false` or `true` literal.
106
107### Commit type
108
109This type cannot be printed. The following methods are defined.
110
111* `description() -> String`
112* `change_id() -> ChangeId`
113* `commit_id() -> CommitId`
114* `parents() -> List<Commit>`
115* `author() -> Signature`
116* `committer() -> Signature`
117* `signature() -> Option<CryptographicSignature>`
118* `mine() -> Boolean`: Commits where the author's email matches the email of the current
119 user.
120* `working_copies() -> String`: For multi-workspace repository, indicate
121 working-copy commit as `<workspace name>@`.
122* `current_working_copy() -> Boolean`: True for the working-copy commit of the
123 current workspace.
124* `bookmarks() -> List<CommitRef>`: Local and remote bookmarks pointing to the
125 commit. A tracking remote bookmark will be included only if its target is
126 different from the local one.
127* `local_bookmarks() -> List<CommitRef>`: All local bookmarks pointing to the
128 commit.
129* `remote_bookmarks() -> List<CommitRef>`: All remote bookmarks pointing to the
130 commit.
131* `tags() -> List<CommitRef>`
132* `git_refs() -> List<CommitRef>`
133* `git_head() -> Boolean`: True for the Git `HEAD` commit.
134* `divergent() -> Boolean`: True if the commit's change id corresponds to multiple
135 visible commits.
136* `hidden() -> Boolean`: True if the commit is not visible (a.k.a. abandoned).
137* `immutable() -> Boolean`: True if the commit is included in [the set of
138 immutable commits](config.md#set-of-immutable-commits).
139* `contained_in(revset: String) -> Boolean`: True if the commit is included in [the provided revset](revsets.md).
140* `conflict() -> Boolean`: True if the commit contains merge conflicts.
141* `empty() -> Boolean`: True if the commit modifies no files.
142* `diff([files: String]) -> TreeDiff`: Changes from the parents within [the
143 `files` expression](filesets.md). All files are compared by default, but it is
144 likely to change in future version to respect the command line path arguments.
145* `root() -> Boolean`: True if the commit is the root commit.
146
147### CommitId / ChangeId type
148
149The following methods are defined.
150
151* `.normal_hex() -> String`: Normal hex representation (0-9a-f), useful for
152 ChangeId, whose canonical hex representation is "reversed" (z-k).
153* `.short([len: Integer]) -> String`
154* `.shortest([min_len: Integer]) -> ShortestIdPrefix`: Shortest unique prefix.
155
156### CommitRef type
157
158The following methods are defined.
159
160* `.name() -> String`: Local bookmark or tag name.
161* `.remote() -> String`: Remote name or empty if this is a local ref.
162* `.present() -> Boolean`: True if the ref points to any commit.
163* `.conflict() -> Boolean`: True if [the bookmark or tag is
164 conflicted](bookmarks.md#conflicts).
165* `.normal_target() -> Option<Commit>`: Target commit if the ref is not
166 conflicted and points to a commit.
167* `.removed_targets() -> List<Commit>`: Old target commits if conflicted.
168* `.added_targets() -> List<Commit>`: New target commits. The list usually
169 contains one "normal" target.
170* `.tracked() -> Boolean`: True if the ref is tracked by a local ref. The local
171 ref might have been deleted (but not pushed yet.)
172* `.tracking_present() -> Boolean`: True if the ref is tracked by a local ref,
173 and if the local ref points to any commit.
174* `.tracking_ahead_count() -> SizeHint`: Number of commits ahead of the tracking
175 local ref.
176* `.tracking_behind_count() -> SizeHint`: Number of commits behind of the
177 tracking local ref.
178
179### ConfigValue type
180
181This type can be printed in TOML syntax. The following methods are defined.
182
183* `.as_boolean() -> Boolean`: Extract boolean.
184* `.as_integer() -> Integer`: Extract integer.
185* `.as_string() -> String`: Extract string. This does not convert non-string
186 value (e.g. integer) to string.
187* `.as_string_list() -> List<String>`: Extract list of strings.
188
189### CryptographicSignature type
190
191The following methods are defined.
192
193* `.status() -> String`: The signature's status (`"good"`, `"bad"`, `"unknown"`, `"invalid"`).
194* `.key() -> String`: The signature's key id representation (for GPG, this is the key fingerprint).
195* `.display() -> String`: The signature's display string (for GPG this is the formatted primary user ID).
196
197!!! warning
198
199 Calling any of `.status()`, `.key()`, or `.display()` is slow, as it incurs
200 the performance cost of verifying the signature (for example shelling out
201 to `gpg` or `ssh-keygen`). Though consecutive calls will be faster, because
202 the backend caches the verification result.
203
204!!! info
205
206 As opposed to calling any of `.status()`, `.key()`, or `.display()`,
207 checking for signature presence through boolean coercion is fast:
208 ```
209 if(commit.signature(), "commit has a signature", "commit is unsigned")
210 ```
211
212### DiffStats type
213
214This type can be printed as a histogram of the changes. The following methods
215are defined.
216
217* `.total_added() -> Integer`: Total number of insertions.
218* `.total_removed() -> Integer`: Total number of deletions.
219
220### Email type
221
222The email field of a signature may or may not look like an email address. It may
223be empty, may not contain the symbol `@`, and could in principle contain
224multiple `@`s.
225
226The following methods are defined.
227
228* `.local() -> String`: the part of the email before the first `@`, usually the
229 username.
230* `.domain() -> String`: the part of the email after the first `@` or the empty
231 string.
232
233### Integer type
234
235No methods are defined.
236
237### List type
238
239A list can be implicitly converted to `Boolean`. The following methods are
240defined.
241
242* `.len() -> Integer`: Number of elements in the list.
243* `.join(separator: Template) -> Template`: Concatenate elements with
244 the given `separator`.
245* `.filter(|item| expression) -> List`: Filter list elements by predicate
246 `expression`. Example: `description.lines().filter(|s| s.contains("#"))`
247* `.map(|item| expression) -> ListTemplate`: Apply template `expression`
248 to each element. Example: `parents.map(|c| c.commit_id().short())`
249
250### ListTemplate type
251
252The following methods are defined. See also the `List` type.
253
254* `.join(separator: Template) -> Template`
255
256### Operation type
257
258This type cannot be printed. The following methods are defined.
259
260* `current_operation() -> Boolean`
261* `description() -> String`
262* `id() -> OperationId`
263* `tags() -> String`
264* `time() -> TimestampRange`
265* `user() -> String`
266* `snapshot() -> Boolean`: True if the operation is a snapshot operation.
267* `root() -> Boolean`: True if the operation is the root operation.
268
269### OperationId type
270
271The following methods are defined.
272
273* `.short([len: Integer]) -> String`
274
275### Option type
276
277An option can be implicitly converted to `Boolean` denoting whether the
278contained value is set. If set, all methods of the contained value can be
279invoked. If not set, an error will be reported inline on method call.
280
281### RepoPath type
282
283A slash-separated path relative to the repository root. The following methods
284are defined.
285
286* `.display() -> String`: Format path for display. The formatted path uses
287 platform-native separator, and is relative to the current working directory.
288* `.parent() -> Option<RepoPath>`: Parent directory path.
289
290### ShortestIdPrefix type
291
292The following methods are defined.
293
294* `.prefix() -> String`
295* `.rest() -> String`
296* `.upper() -> ShortestIdPrefix`
297* `.lower() -> ShortestIdPrefix`
298
299### Signature type
300
301The following methods are defined.
302
303* `.name() -> String`
304* `.email() -> Email`
305* `.timestamp() -> Timestamp`
306
307### SizeHint type
308
309This type cannot be printed. The following methods are defined.
310
311* `.lower() -> Integer`: Lower bound.
312* `.upper() -> Option<Integer>`: Upper bound if known.
313* `.exact() -> Option<Integer>`: Exact value if upper bound is known and it
314 equals to the lower bound.
315* `.zero() -> Boolean`: True if upper bound is known and is `0`.
316
317### String type
318
319A string can be implicitly converted to `Boolean`. The following methods are
320defined.
321
322* `.len() -> Integer`: Length in UTF-8 bytes.
323* `.contains(needle: Template) -> Boolean`
324* `.first_line() -> String`
325* `.lines() -> List<String>`: Split into lines excluding newline characters.
326* `.upper() -> String`
327* `.lower() -> String`
328* `.starts_with(needle: Template) -> Boolean`
329* `.ends_with(needle: Template) -> Boolean`
330* `.remove_prefix(needle: Template) -> String`: Removes the passed prefix, if present
331* `.remove_suffix(needle: Template) -> String`: Removes the passed suffix, if present
332* `.trim() -> String`: Removes leading and trailing whitespace
333* `.trim_start() -> String`: Removes leading whitespace
334* `.trim_end() -> String`: Removes trailing whitespace
335* `.substr(start: Integer, end: Integer) -> String`: Extract substring. The
336 `start`/`end` indices should be specified in UTF-8 bytes. Negative values
337 count from the end of the string.
338* `.escape_json() -> String`: Serializes the string in JSON format. This
339 function is useful for making machine-readable templates. For example, you
340 can use it in a template like `'{ "foo": ' ++ foo.escape_json() ++ ' }'` to
341 return a JSON/JSONL.
342
343#### String literals
344
345String literals must be surrounded by single or double quotes (`'` or `"`).
346A double-quoted string literal supports the following escape sequences:
347
348* `\"`: double quote
349* `\\`: backslash
350* `\t`: horizontal tab
351* `\r`: carriage return
352* `\n`: new line
353* `\0`: null
354* `\e`: escape (i.e., `\x1b`)
355* `\xHH`: byte with hex value `HH`
356
357Other escape sequences are not supported. Any UTF-8 characters are allowed
358inside a string literal, with two exceptions: unescaped `"`-s and uses of `\`
359that don't form a valid escape sequence.
360
361A single-quoted string literal has no escape syntax. `'` can't be expressed
362inside a single-quoted string literal.
363
364### Template type
365
366Most types can be implicitly converted to `Template`. No methods are defined.
367
368### Timestamp type
369
370The following methods are defined.
371
372* `.ago() -> String`: Format as relative timestamp.
373* `.format(format: String) -> String`: Format with [the specified strftime-like
374 format string](https://docs.rs/chrono/latest/chrono/format/strftime/).
375* `.utc() -> Timestamp`: Convert timestamp into UTC timezone.
376* `.local() -> Timestamp`: Convert timestamp into local timezone.
377* `.after(date: String) -> Boolean`: True if the timestamp is exactly at or after the given date.
378* `.before(date: String) -> Boolean`: True if the timestamp is before, but not including, the given date.
379
380### TimestampRange type
381
382The following methods are defined.
383
384* `.start() -> Timestamp`
385* `.end() -> Timestamp`
386* `.duration() -> String`
387
388### TreeDiff type
389
390This type cannot be printed. The following methods are defined.
391
392* `.files() -> List<TreeDiffEntry>`: Changed files.
393* `.color_words([context: Integer]) -> Template`: Format as a word-level diff
394 with changes indicated only by color.
395* `.git([context: Integer]) -> Template`: Format as a Git diff.
396* `.stat([width: Integer]) -> DiffStats`: Calculate stats of changed lines.
397* `.summary() -> Template`: Format as a list of status code and path pairs.
398
399### TreeDiffEntry type
400
401This type cannot be printed. The following methods are defined.
402
403* `.path() -> RepoPath`: Path to the entry. If the entry is a copy/rename, this
404 points to the target (or right) entry.
405* `.status() -> String`: One of `"modified"`, `"added"`, `"removed"`,
406 `"copied"`, or `"renamed"`.
407* `.source() -> TreeEntry`: The source (or left) entry.
408* `.target() -> TreeEntry`: The target (or right) entry.
409
410### TreeEntry type
411
412This type cannot be printed. The following methods are defined.
413
414* `.path() -> RepoPath`: Path to the entry.
415* `.conflict() -> Boolean`: True if the entry is a merge conflict.
416* `.file_type() -> String`: One of `"file"`, `"symlink"`, `"tree"`,
417 `"git-submodule"`, or `"conflict"`.
418* `.executable() -> Boolean`: True if the entry is an executable file.
419
420## Configuration
421
422The default templates and aliases() are defined in the `[templates]` and
423`[template-aliases]` sections of the config respectively. The exact definitions
424can be seen in the [`cli/src/config/templates.toml`][1] file in jj's source
425tree.
426
427[1]: https://github.com/jj-vcs/jj/blob/main/cli/src/config/templates.toml
428
429<!--- TODO: Find a way to embed the default config files in the docs -->
430
431New keywords and functions can be defined as aliases, by using any
432combination of the predefined keywords/functions and other aliases.
433
434Alias functions can be overloaded by the number of parameters. However, builtin
435functions will be shadowed by name, and can't co-exist with aliases.
436
437For example:
438
439```toml
440[template-aliases]
441'commit_change_ids' = '''
442concat(
443 format_field("Commit ID", commit_id),
444 format_field("Change ID", change_id),
445)
446'''
447'format_field(key, value)' = 'key ++ ": " ++ value ++ "\n"'
448```
449
450## Examples
451
452Get short commit IDs of the working-copy parents:
453
454```sh
455jj log --no-graph -r @ -T 'parents.map(|c| c.commit_id().short()).join(",")'
456```
457
458Show machine-readable list of full commit and change IDs:
459
460```sh
461jj log --no-graph -T 'commit_id ++ " " ++ change_id ++ "\n"'
462```