mirrors/jj
1
0
Fork 1
mirror of https://github.com/martinvonz/jj.git synced 2025-01-02 18:01:05 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 7
jj/docs/templates.md
Yuya Nishihara c52efd9df3 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-10 16:07:55 +09:00

4.1 KiB
Raw Blame History

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
  • parent_commit_ids: List<CommitId>
  • 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.

  • 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.
  • 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.

List type

The following methods are defined.

  • .join(separator: Template) -> Template: Concatenate elements with the given separator.

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
  • .lines() -> List<String>: Split into lines excluding newline characters.
  • .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 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:

[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"'