From 11d0919552053cdebd99ee073522ab9b6cc86902 Mon Sep 17 00:00:00 2001 From: Ilya Grigoriev Date: Sun, 19 Oct 2025 18:43:20 -0700 Subject: [PATCH] docs templates: document the `label` function and color labels better I originally meant to make a smaller change, but I ended up reordering the discussion of different topics, resulting in a large diff. Fixes #7778 --- docs/templates.md | 38 +++++++++++++++++++++++++++++--------- 1 file changed, 29 insertions(+), 9 deletions(-) diff --git a/docs/templates.md b/docs/templates.md index 5f8aba3ee7..177752a638 100644 --- a/docs/templates.md +++ b/docs/templates.md @@ -72,8 +72,9 @@ The following functions are defined. append the `ellipsis` to the result. * `hash(content: Stringify) -> String`: Hash the input and return a hexadecimal string representation of the digest. -* `label(label: Stringify, content: Template) -> Template`: Apply label to - the content. The `label` is evaluated as a space-separated string. +* `label(label: Stringify, content: Template) -> Template`: Apply a custom + [color label](#color-labels) to the content. The `label` is evaluated as a + space-separated string. * `raw_escape_sequence(content: Template) -> Template`: Preserves any escape sequences in `content` (i.e., bypasses sanitization) and strips labels. Note: This function is intended for escape sequences and as such, its output @@ -621,20 +622,39 @@ The following methods are defined. ## Color labels -Template fragments are usually labeled with the command name, the context (or -the top-level object), and the method names. You can [customize the output -colors][config-colors] by using these labels. +You can [customize the output colors][config-colors] by using color labels. `jj` +adds some labels automatically; they can also be added manually. -For example, the following template is labeled as `op_log operation id short`: +Template fragments are usually **automatically** labeled with the command name, +the context (or the top-level object), and the method names. For example, the +following template is labeled as `op_log operation id short` automatically: ```sh jj op log -T 'self.id().short()' ``` -In addition to that, you can insert arbitrary labels by `label(label, content)` -function. +The exact names of such labels are often straightforward, but are not currently +documented. You can discover the actual label names used with the +`--color=debug` option, e.g. -To inspect how output fragments are labeled, use `--color=debug` option. +```sh +jj op log -T 'self.id().short()' --color=debug +``` + +Additionally, you can **manually** insert arbitrary labels using the +`label(label, content)` function. For example, + +```sh +jj op log -T '"ID: " ++ self.id().short().substr(0, 1) ++ label("id short", "")' +``` + +will print "ID:" in the default style, and the string `` in the same +style as the first character of the id. It would also be fine to use an +arbitrary template instead of the string `""`, possibly including +nested invocations of `label()`. + +You are free to use custom label names as well. This will only have a visible +effect if you also [customize their colors][config-colors] explicitly. [config-colors]: config.md#custom-colors-and-styles