ok/jj
1
0
Fork 0
forked from mirrors/jj
Code Pull requests Activity
jj/docs/templates.md

164 lines
3.9 KiB
Markdown
Raw Normal View History

docs: document template syntax, keywords and methods Not all keywords and methods have description, but I think the function signature should help understand the behavior.
2023-03-01 09:18:00 +00:00
# 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.
### Commit keywords
The following keywords can be used in `jj log`/`jj obslog` templates.
* `description: String`
* `change_id: ChangeId`
* `commit_id: CommitId`
templater: add "parent_commit_ids" keyword A list type isn't so useful without a map operation, but List<CommitId> is at least printable. Maybe we can experiment with it to craft a map operation. If a map operation is introduced, this keyword might be replaced with "parents.map(|commit| commit.commit_id)", where parents is of List<Commit> type, and the .map() method will probably return List<Template>.
2023-03-06 12:02:57 +00:00
* `parent_commit_ids: List<CommitId>`
docs: document template syntax, keywords and methods Not all keywords and methods have description, but I think the function signature should help understand the behavior.
2023-03-01 09:18:00 +00:00
* `author: Signature`
* `committer: Signature`
* `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: String`
* `tags: String`
* `git_refs: String`
* `git_head: String`
* `divergent: Boolean`: True if the change id corresponds to multiple visible
commits.
* `conflict: Boolean`: True if the commit contains merge conflicts.
* `empty: Boolean`: True if the commit modifies no files.
### Operation keywords
The following keywords can be used in `jj op log` templates.
* `current_operation: Boolean`
* `description: String`
* `id: OperationId`
* `tags: String`
* `time: TimestampRange`
* `user: String`
## Operators
The following operators are supported.
* `x.f()`: Method call.
* `x ++ y`: Concatenate `x` and `y` templates.
## Global functions
The following functions are defined.
templater: add indent(prefix, content) function The argument order is different from Mercurial's indent() function. I think indent(prefix, content) is more readable for lengthy content. However, indent(content, prefix, ...) might be better if we want to add an optional firstline_prefix argument.
2023-03-02 08:16:22 +00:00
* `indent(prefix: Template, content: Template) -> Template`: Indent
non-empty lines by the given `prefix`.
docs: document template syntax, keywords and methods Not all keywords and methods have description, but I think the function signature should help understand the behavior.
2023-03-01 09:18:00 +00:00
* `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.
* `concat(content: Template...) -> Template`:
Same as `content_1 ++ ... ++ content_n`.
* `separate(separator: Template, content: Template...) -> Template`:
Insert separator between **non-empty** contents.
## Types
### Boolean type
No methods are defined.
### 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.
templater: add "parent_commit_ids" keyword A list type isn't so useful without a map operation, but List<CommitId> is at least printable. Maybe we can experiment with it to craft a map operation. If a map operation is introduced, this keyword might be replaced with "parents.map(|commit| commit.commit_id)", where parents is of List<Commit> type, and the .map() method will probably return List<Template>.
2023-03-06 12:02:57 +00:00
### List type
No methods are defined.
docs: document template syntax, keywords and methods Not all keywords and methods have description, but I think the function signature should help understand the behavior.
2023-03-01 09:18:00 +00:00
### OperationId type
The following methods are defined.
* `.short([len: Integer]) -> String`
### 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.
* `.contains(needle: Template) -> Boolean`
* `.first_line() -> String`
templater: add string.lines() method This wouldn't be used much in practice, but is useful for writing tests of list methods.
2023-03-07 09:19:50 +00:00
* `.lines() -> List<String>`: Split into lines excluding newline characters.
docs: document template syntax, keywords and methods Not all keywords and methods have description, but I think the function signature should help understand the behavior.
2023-03-01 09:18:00 +00:00
* `.upper() -> String`
* `.lower() -> String`
### Template type
Any types can be implicitly converted to `Template`. No methods are defined.
### Timestamp type
The following methods are defined.
* `.ago() -> String`: Format as relative timestamp.
### TimestampRange type
The following methods are defined.
* `.start() -> Timestamp`
* `.end() -> Timestamp`
* `.duration() -> String`
## Configuration
[The default templates and aliases](../src/config/templates.toml) are defined
in the `[templates]` and `[template-aliases]` sections respectively.
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"'
```
Copy permalink