mirror of
https://github.com/martinvonz/jj.git
synced 2024-10-24 15:43:12 +00:00
5b769c5c9e
Since fileset/revset/template expressions are specified as command-line arguments, it's sometimes convenient to use single quotes instead of double quotes. Various scripting languages parse single-quoted strings in various ways, but I choose the TOML rule because it's simple and practically useful. TOML is our config language, so copying the TOML syntax would be less surprising than borrowing it from another language. https://github.com/toml-lang/toml/issues/188
259 lines
8.2 KiB
Markdown
259 lines
8.2 KiB
Markdown
# 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`/`jj obslog` 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.f()`: Method call.
|
|
* `-x`: Negate integer value.
|
|
* `!x`: Logical not.
|
|
* `x && y`: Logical and, short-circuiting.
|
|
* `x || y`: Logical or, short-circuiting.
|
|
* `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`.
|
|
* `label(label: Template, content: Template) -> Template`: Apply label to
|
|
the content. The `label` is evaluated as a space-separated string.
|
|
* `if(condition: Boolean, then: Template[, else: Template]) -> Template`:
|
|
Conditionally evaluate `then`/`else` template content.
|
|
* `coalesce(content: Template...) -> Template`: Returns the first **non-empty**
|
|
content.
|
|
* `concat(content: Template...) -> Template`:
|
|
Same as `content_1 ++ ... ++ content_n`.
|
|
* `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.
|
|
|
|
## Types
|
|
|
|
### Boolean type
|
|
|
|
No methods are defined. Can be constructed with `false` or `true` literal.
|
|
|
|
### Commit type
|
|
|
|
This type cannot be printed. The following methods are defined.
|
|
|
|
* `description() -> String`
|
|
* `change_id() -> ChangeId`
|
|
* `commit_id() -> CommitId`
|
|
* `parents() -> List<Commit>`
|
|
* `author() -> Signature`
|
|
* `committer() -> Signature`
|
|
* `mine() -> Boolean`: Commits where the author's email matches the email of the current
|
|
user.
|
|
* `working_copies() -> String`: For multi-workspace repository, indicate
|
|
working-copy commit as `<workspace name>@`.
|
|
* `current_working_copy() -> Boolean`: True for the working-copy commit of the
|
|
current workspace.
|
|
* `branches() -> List<RefName>`: Local and remote branches pointing to the commit.
|
|
A tracking remote branch will be included only if its target is different
|
|
from the local one.
|
|
* `local_branches() -> List<RefName>`: All local branches pointing to the commit.
|
|
* `remote_branches() -> List<RefName>`: All remote branches pointing to the commit.
|
|
* `tags() -> List<RefName>`
|
|
* `git_refs() -> List<RefName>`
|
|
* `git_head() -> Option<RefName>`
|
|
* `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).
|
|
* `immutable() -> Boolean`: True if the commit is included in [the set of
|
|
immutable commits](config.md#set-of-immutable-commits).
|
|
* `conflict() -> Boolean`: True if the commit contains merge conflicts.
|
|
* `empty() -> Boolean`: True if the commit modifies no files.
|
|
* `root() -> Boolean`: True if the commit is the root commit.
|
|
|
|
### CommitId / ChangeId type
|
|
|
|
The following methods are defined.
|
|
|
|
* `.short([len: Integer]) -> String`
|
|
* `.shortest([min_len: Integer]) -> ShortestIdPrefix`: Shortest unique prefix.
|
|
|
|
### Integer type
|
|
|
|
No methods are defined.
|
|
|
|
### List type
|
|
|
|
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`.
|
|
* `.map(|item| expression) -> ListTemplate`: Apply template `expression`
|
|
to each element. Example: `parents.map(|c| c.commit_id().short())`
|
|
|
|
### ListTemplate type
|
|
|
|
The following methods are defined. See also the `List` type.
|
|
|
|
* `.join(separator: Template) -> Template`
|
|
|
|
### Operation type
|
|
|
|
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.
|
|
* `root() -> Boolean`: True if the operation is the root operation.
|
|
|
|
### OperationId type
|
|
|
|
The following methods are defined.
|
|
|
|
* `.short([len: Integer]) -> String`
|
|
|
|
### Option type
|
|
|
|
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.
|
|
|
|
### RefName type
|
|
|
|
The following methods are defined.
|
|
|
|
* `.name() -> String`: Local branch or tag name.
|
|
* `.remote() -> String`: Remote name or empty if this is a local ref.
|
|
|
|
### ShortestIdPrefix type
|
|
|
|
The following methods are defined.
|
|
|
|
* `.prefix() -> String`
|
|
* `.rest() -> String`
|
|
* `.upper() -> ShortestIdPrefix`
|
|
* `.lower() -> ShortestIdPrefix`
|
|
|
|
### Signature type
|
|
|
|
The following methods are defined.
|
|
|
|
* `.name() -> String`
|
|
* `.email() -> String`
|
|
* `.username() -> String`
|
|
* `.timestamp() -> Timestamp`
|
|
|
|
### String type
|
|
|
|
A string can be implicitly converted to `Boolean`. The following methods are
|
|
defined.
|
|
|
|
* `.len() -> Integer`: Length in UTF-8 bytes.
|
|
* `.contains(needle: Template) -> Boolean`
|
|
* `.first_line() -> String`
|
|
* `.lines() -> List<String>`: Split into lines excluding newline characters.
|
|
* `.upper() -> String`
|
|
* `.lower() -> String`
|
|
* `.starts_with(needle: Template) -> Boolean`
|
|
* `.ends_with(needle: Template) -> Boolean`
|
|
* `.remove_prefix(needle: Template) -> String`: Removes the passed prefix, if present
|
|
* `.remove_suffix(needle: Template) -> String`: Removes the passed suffix, if present
|
|
* `.substr(start: Integer, end: Integer) -> String`: Extract substring. The
|
|
`start`/`end` indices should be specified in UTF-8 bytes. Negative values
|
|
count from the end of the string.
|
|
|
|
#### String literals
|
|
|
|
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
|
|
|
|
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.
|
|
|
|
### Template type
|
|
|
|
Most types can be implicitly converted to `Template`. No methods are defined.
|
|
|
|
### Timestamp type
|
|
|
|
The following methods are defined.
|
|
|
|
* `.ago() -> String`: Format as relative timestamp.
|
|
* `.format(format: String) -> 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.
|
|
|
|
### TimestampRange type
|
|
|
|
The following methods are defined.
|
|
|
|
* `.start() -> Timestamp`
|
|
* `.end() -> Timestamp`
|
|
* `.duration() -> String`
|
|
|
|
## 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` file in jj's source tree.
|
|
|
|
<!--- TODO: Find a way to embed the default config files in the docs -->
|
|
|
|
New keywords and functions can be defined as aliases, by using any
|
|
combination of the predefined keywords/functions and other aliases.
|
|
|
|
For example:
|
|
|
|
```toml
|
|
[template-aliases]
|
|
'commit_change_ids' = '''
|
|
concat(
|
|
format_field("Commit ID", commit_id),
|
|
format_field("Change ID", commit_id),
|
|
)
|
|
'''
|
|
'format_field(key, value)' = 'key ++ ": " ++ value ++ "\n"'
|
|
```
|