Skip to content

docs templates: document the label function and color labels better #7780

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs templates: document the label function and color labels better #7780

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 29 additions & 9 deletions docs/templates.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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("op_log operation id short", "<redacted>")'
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: perhaps, the latter label() should be label("id short") or label("id short substr").

It's also good to use practical example such as label(if(current_operation, "current_operation")).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks!

perhaps, the latter label() should be label("id short") or label("id short substr").

Do you have any thoughts on how a user could discover the fact that "id short" is sufficient here? Or do you think we don't need to explain it?

If your preference is simply to replace the label with "id short" with no further explanation, I can live with that.

It's also good to use practical example such as label(if(current_operation, "current_operation")).

I had this thought too, but a simple enough example that felt complete didn't come to me.

For both issues, linking to the built-in colors.toml might help. I kept avoiding it since it is linked indirectly via the "customizing colors" link, and because I was wondering whether to explain things comprehensively, I'd need to insert excerpts from there that would make everything longer. But maybe it makes sense to add it after all in some way.

So, I think both of your points are good, but I don't have an immediate idea for implementing them nicely. I'd be more than OK with postponing them to a potential follow-up.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't have a good readable explanation, and I would just suggest --color=debug to understand the behavior. It's also not so obvious that self doesn't contribute to auto-labeling, substr is labeled, etc.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was thinking more about explaining the fact that id short gets the same colors as op_log operation id short.

In any case, unless I think of something else or you have more thoughts, I guess I'll just replace it with "id short" and perhaps people with questions will ask.

```

will print "ID:" in the default style, and the string `<redacted>` 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 `"<redacted>"`, 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

Expand Down