Skip to content
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

docs: Move language references to a Reference section #5375

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

docs: Move language references to a Reference section #5375

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
939f404
docs: Move language references to a Reference section
jennings Jan 9, 2025
98c2881
docs: Extract well-known template aliases to their own configuration …
jennings Jan 9, 2025
d38baae
docs: Extract well-known revset aliases to their own page
jennings Jan 9, 2025
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
2 changes: 1 addition & 1 deletion CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -708,7 +708,7 @@ Thanks to the people who made this release happen!
* `jj backout --revision` has been renamed to `jj backout --revisions`.
The short alias `-r` is still supported.

* [The default `immutable_heads()` set](docs/config.md#set-of-immutable-commits)
* [The default `immutable_heads()` set](docs/revset-config.md#immutable_heads)
now includes `untracked_remote_branches()` with the assumption that untracked
branches aren't managed by you. Therefore, untracked branches are no longer
displayed in `jj log` by default.
Expand Down
4 changes: 2 additions & 2 deletions cli/src/commands/log.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,9 +54,9 @@ use crate::ui::Ui;
/// rendered as a synthetic node labeled "(elided revisions)".
///
/// The working-copy commit is indicated by a `@` symbol in the graph. Immutable
/// revisions (https://jj-vcs.github.io/jj/latest/config/#set-of-immutable-commits)
/// revisions (https://jj-vcs.github.io/jj/latest/revset-aliases/#immutable_heads)
/// have a `◆` symbol. Other commits have a `○` symbol. To customize these
/// symbols, see https://jj-vcs.github.io/jj/latest/config/#node-style.
/// symbols, see https://jj-vcs.github.io/jj/latest/template-config/#log-nodes.
#[derive(clap::Args, Clone, Debug)]
pub(crate) struct LogArgs {
/// Which revisions to show
Expand Down
2 changes: 1 addition & 1 deletion cli/tests/[email protected]
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1361,7 +1361,7 @@ Renders a graphical view of the project's history, ordered with children before

Spans of revisions that are not included in the graph per `--revisions` are rendered as a synthetic node labeled "(elided revisions)".

The working-copy commit is indicated by a `@` symbol in the graph. Immutable revisions (https://jj-vcs.github.io/jj/latest/config/#set-of-immutable-commits) have a `◆` symbol. Other commits have a `○` symbol. To customize these symbols, see https://jj-vcs.github.io/jj/latest/config/#node-style.
The working-copy commit is indicated by a `@` symbol in the graph. Immutable revisions (https://jj-vcs.github.io/jj/latest/revset-config/#immutable_heads) have a `◆` symbol. Other commits have a `○` symbol. To customize these symbols, see https://jj-vcs.github.io/jj/latest/config/#node-style.

**Usage:** `jj log [OPTIONS] [FILESETS]...`

Expand Down
189 changes: 28 additions & 161 deletions docs/config.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -169,32 +169,18 @@ default-command = ["log", "--reversed"]

### Default description

The editor content of a commit description can be populated by the
`draft_commit_description` template.

```toml
[templates]
draft_commit_description = '''
concat(
description,
surround(
"\nJJ: This commit contains the following changes:\n", "",
indent("JJ: ", diff.stat(72)),
),
"\nJJ: ignore-rest\n",
diff.git(),
)
'''
```

The value of the `ui.default-description` setting can also be used in order to
fill in things like BUG=, TESTED= etc.
The value of the `ui.default-description` setting can be used in order to fill
in things like BUG=, TESTED= etc.

```toml
[ui]
default-description = "\n\nTESTED=TODO"
```

The contents of the editor when editing descriptions (including comments) can be
changed with the setting
[`template-aliases.draft_commit_description`](template-config.md#description-editor-contents).

### Diff colors and styles

In color-words and git diffs, word-level hunks are rendered with underline. You
Expand Down Expand Up @@ -320,69 +306,23 @@ page](conflicts.md#conflict-markers).

### Set of immutable commits
jennings marked this conversation as resolved.
Show resolved Hide resolved

You can configure the set of immutable commits via
`revset-aliases."immutable_heads()"`. The default set of immutable heads is
`builtin_immutable_heads()`, which in turn is defined as
`present(trunk()) | tags() | untracked_remote_bookmarks()`. For example, to
also consider the `release@origin` bookmark immutable:

```toml
[revset-aliases]
"immutable_heads()" = "builtin_immutable_heads() | release@origin"
```

To prevent rewriting commits authored by other users:

```toml
# The `trunk().. &` bit is an optimization to scan for non-`mine()` commits
# only among commits that are not in `trunk()`.
[revset-aliases]
"immutable_heads()" = "builtin_immutable_heads() | (trunk().. & ~mine())"
```

Ancestors of the configured set are also immutable. The root commit is always
immutable even if the set is empty.
You can change which revisions are immutable by setting the
[`immutable_heads()` revset alias](revset-config.md#immutable_heads).

## Log

### Default revisions

You can configure the revisions `jj log` would show when neither `-r` nor any paths are specified.

```toml
[revsets]
# Show commits that are not in `main@origin`
log = "main@origin.."
```

The default value for `revsets.log` is
`'present(@) | ancestors(immutable_heads().., 2) | present(trunk())'`.
You can change which revisions are logged by default with the [`revsets.log`
setting](revset-config.md#revsets-log).

### Default Template

You can configure the template used when no `-T` is specified.

- `templates.log` for `jj log`
- `templates.op_log` for `jj op log`
- `templates.show` for `jj show`
See the following documentation to change the default templates:

```toml
[templates]
# Use builtin log template
log = "builtin_log_compact"
# Use builtin op log template
op_log = "builtin_op_log_compact"
# Use builtin show template
show = "builtin_log_detailed"
```

If you want to see the full description when you do `jj log` you can add this to
your config:

```toml
[templates]
log = "builtin_log_compact_full_description"
```
* [`templates.log`](template-config.md#log)
* [`templates.op_log`](template-config.md#operation-log)
* [`templates.show`](template-config.md#show)

### Graph style

Expand All @@ -394,25 +334,8 @@ graph.style = "square"

#### Node style

The symbols used to represent commits or operations can be customized via
templates.

- `templates.log_node` for commits (with `Option<Commit>` keywords)
- `templates.op_log_node` for operations (with `Operation` keywords)

For example:
```toml
[templates]
log_node = '''
coalesce(
if(!self, "🮀"),
if(current_working_copy, "@"),
if(root, "┴"),
if(immutable, "●", "○"),
)
'''
op_log_node = 'if(current_operation, "@", "○")'
```
See [`templates.log_node`](template-config.md#log-nodes) and
[`templates.op_log_node`](template-config.md#operation-log-nodes).

### Wrap log content

Expand All @@ -426,84 +349,28 @@ log-word-wrap = true

### Display of commit and change ids

jennings marked this conversation as resolved.
Show resolved Hide resolved
Can be customized by the `format_short_id()` template alias.
To change the presentation of commit and change ids, adjust the
[`format_short_id()` template alias](template-config.md#format_short_id). The
linked doc also explains how to change them separately.

```toml
[template-aliases]
# Highlight unique prefix and show at least 12 characters (default)
'format_short_id(id)' = 'id.shortest(12)'
# Just the shortest possible unique prefix
'format_short_id(id)' = 'id.shortest()'
# Show unique prefix and the rest surrounded by brackets
'format_short_id(id)' = 'id.shortest(12).prefix() ++ "[" ++ id.shortest(12).rest() ++ "]"'
# Always show 12 characters
'format_short_id(id)' = 'id.short(12)'
```

To customize these separately, use the `format_short_commit_id()` and
`format_short_change_id()` aliases:

```toml
[template-aliases]
# Uppercase change ids. `jj` treats change and commit ids as case-insensitive.
'format_short_change_id(id)' = 'format_short_id(id).upper()'
```

To get shorter prefixes for certain revisions, set `revsets.short-prefixes`:

```toml
[revsets]
# Prioritize the current bookmark
short-prefixes = "(main..@)::"
```
To change which revisions get the shortest prefixes, see [commit and change Id
short prefixes](revset-config.md#revsets-short-prefixes).

### Relative timestamps
jennings marked this conversation as resolved.
Show resolved Hide resolved

Can be customized by the `format_timestamp()` template alias.

```toml
[template-aliases]
# Full timestamp in ISO 8601 format
'format_timestamp(timestamp)' = 'timestamp'
# Relative timestamp rendered as "x days/hours/seconds ago"
'format_timestamp(timestamp)' = 'timestamp.ago()'
```

`jj op log` defaults to relative timestamps. To use absolute timestamps, you
will need to modify the `format_time_range()` template alias.

```toml
[template-aliases]
'format_time_range(time_range)' = 'time_range.start() ++ " - " ++ time_range.end()'
```
You can use relative timestamps by adjusting the [`format_timestamp()` template
alias](template-config.md#format_timestamp).
Copy link
Contributor

Choose a reason for hiding this comment

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

Do we need links per sub section? I think something like this is good enough:

## Log

...

### Template and style

See [Log template configuration](..) for details .. blah blah

I think related config variables can also be moved there. For example, ui.log-word-wrap is NOT a template parameter, but it applies to log template output.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

This is a request to remove headings like "Relative timestamps", "Author format", etc., and just have one blanket section "Template and style" that links over to the template-config.md page. Do I understand correctly?

@ilyagr suggested keeping these headings so incoming links don't break, like the link to #node-style that jj log --help outputs.

But, now that I've found how to add custom anchors to the page, I could make all those anchors go to the relevant blanket section.

### Template and style

[](){#relative-timestamps}[](){#author-format}...

See [Log template configuration](template-config.md) for more information.

What do you think?

Copy link
Contributor

Choose a reason for hiding this comment

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

This is a request to remove headings like "Relative timestamps", "Author format", etc., and just have one blanket section "Template and style" that links over to the template-config.md page.

Yes. I don't think we would want to update both config.md and template/revset-config.md when adding new sections.


### Author format

Can be customized by the `format_short_signature()` template alias.
jennings marked this conversation as resolved.
Show resolved Hide resolved

```toml
[template-aliases]
# Full email address (default)
'format_short_signature(signature)' = 'signature.email()'
# Both name and email address
'format_short_signature(signature)' = 'signature'
# Username part of the email address
'format_short_signature(signature)' = 'signature.username()'
```
The [`format_short_signature()` template
alias](template-config.md#format_short_signature) controls how commit authors
are displayed.

### Commit timestamp

Commits have both an "author timestamp" and "committer timestamp". By default,
Copy link
Contributor

Choose a reason for hiding this comment

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

Ditto. I'm wondering if this paragraph can also be shortened.

jj displays the committer timestamp, but can be changed to show the author
timestamp instead.

The function must return a timestamp because the return value will likely be
formatted with `format_timestamp()`.

```toml
[template-aliases]
'commit_timestamp(commit)' = 'commit.author().timestamp()'
```
The [`commit_timestamp()` template alias](template-config.md#commit_timestamp)
controls whether the author or committer timestamp is displayed in the log.

### Signature format
Copy link
Contributor

Choose a reason for hiding this comment

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

Move "Signature format" to template-config.md?


Expand Down
85 changes: 85 additions & 0 deletions docs/revset-config.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
# Revset configuration

## Configurable revsets

Settings in the `revsets` section configure Jujutsu itself. These revsets may
use any [revset aliases](#revset-aliases) that you have defined.

### `log`: Default log revisions {#revsets-log}

You can configure the revisions `jj log` would show when neither `-r` nor any
paths are specified.

```toml
[revsets]
# Show commits that are not in `main@origin`
log = "main@origin.."
```

The default value for `revsets.log` is
`'present(@) | ancestors(immutable_heads().., 2) | present(trunk())'`.

### `short-prefixes`: Commit and change ID short prefixes {#revsets-short-prefixes}

To control which revisions get priority for shorter prefixes, set
`revsets.short-prefixes`:

```toml
[revsets]
# Prioritize the current bookmark
short-prefixes = "(main..@)::"
```

## Revset aliases

Some revset aliases are built-in to Jujutsu and used to control its behavior.

See the [revset language reference](revsets.md) for more information about the
revset language and defining your own revset aliases.

### `trunk()`: Head of the main line of development {#trunk}

Most teams have a main line of development, usually named `main`, `master`, or
`trunk`. The `trunk()` alias resolves to the bookmark for this branch.

This alias is used in the default values for the [log
revset](#revsets-log) and for
[`immutable_heads()`](#immutable_heads).

When Jujutsu clones a Git repository, it uses the remote's HEAD to set this
revset aliases in the repo's config.

```toml
[revset-aliases]
"trunk()" = "dev@origin"
```

### `immutable_heads()`: Change the set of immutable commits {#immutable_heads}

Controls which commits are immutable. Jujutsu will refuse to modify these
commits unless `--ignore-immutable` is specified.

Many teams have a main line of development, usually named `main`, `master`, or
`trunk`.

Ancestors of the configured set are also immutable. The root commit is always
immutable even if the set is empty.

Default value: `builtin_immutable_heads()`, which in turn is defined as
`present(trunk()) | tags() | untracked_remote_bookmarks()`.

For example, to also consider the `release@origin` bookmark immutable:

```toml
[revset-aliases]
"immutable_heads()" = "builtin_immutable_heads() | release@origin"
```

To prevent rewriting commits authored by other users:

```toml
# The `trunk().. &` bit is an optimization to scan for non-`mine()` commits
# only among commits that are not in `trunk()`.
[revset-aliases]
"immutable_heads()" = "builtin_immutable_heads() | (trunk().. & ~mine())"
```
4 changes: 2 additions & 2 deletions docs/revsets.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Revsets
# Revset language

Jujutsu supports a functional language for selecting a set of revisions.
Expressions in this language are called "revsets" (the idea comes from
Expand Down Expand Up @@ -489,7 +489,7 @@ for a comprehensive list.
* `immutable_heads()`: Resolves to
`present(trunk()) | tags() | untracked_remote_bookmarks()` by default. It is
actually defined as `builtin_immutable_heads()`, and can be overridden as
required. See [here](config.md#set-of-immutable-commits) for details.
required. See [here](revset-config.md#immutable_heads) for details.

* `immutable()`: The set of commits that `jj` treats as immutable. This is
equivalent to `::(immutable_heads() | root())`. It is not recommended to redefine
Expand Down
Loading
Loading