mirrors/jj
1
0
Fork 1
mirror of https://github.com/martinvonz/jj.git synced 2025-01-05 02:53:12 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 9
jj/docs/templates.md

169 lines
4.1 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 fill(width, content) function The parameter order follows indent()/label() functions, but this might be a bad idea because fill() is more likely to have optional parameters. We can instead add template.fill(width) method as well as .indent(prefix). If we take this approach, we'll probably need to add string.fill()/indent() methods, and/or implicit cast at method resolution. The good thing about the method syntax is that we can add string.refill(), etc. for free, without inventing generic labeled template functions. For #1043, I think it's better to add a config like ui.log-word-wrap = true. We could add term_width/graph_width keywords to the templater, but the implementation would be more complicated, and is difficult to use for the basic use case. Unlike Mercurial, our templater doesn't have a context map to override the graph_width stub.
2023-03-04 14:07:14 +00:00
* `fill(width: Integer, content: Template) -> Template`: Fill lines at
the given `width`.
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
templater: add list.join(separator) method The implementation is a bit tricky since we have to combine a property (of C -> Vec<Template<()>> type) and a separator of Template<C> type.
2023-03-06 13:02:39 +00:00
The following methods are defined.
* `.join(separator: Template) -> Template`: Concatenate elements with
the given `separator`.
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
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"'
```
Reference in a new issue Copy permalink