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: Expose config-schema.json in the docs site #5347

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

docs: Expose config-schema.json in the docs site #5347

Show file tree
Hide file tree
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
8 changes: 8 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,14 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
* New `git.sign-on-push` config option to automatically sign commits which are being
pushed to a Git remote.

* Publish `config-schema.json` in the documentation site. Users can now reference
Copy link
Member

Choose a reason for hiding this comment

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

I'd probably say:

The Jujutsu documentation site now publishes a schema for the official configuration file, which can be integrated into your editor for autocomplete, inline errors, and more. Please see the documentation for more on this.

i.e. we normally would link to the docs elsewhere, rather than including the example inline.

Copy link
Author

Choose a reason for hiding this comment

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

Sounds good, thank you!! I wasn't quite sure about how specific to be here. Will update shortly.

the schema in their `~/.config/jj/config.toml` file:

```toml
# Get editor completions based on the config schema
"$schema" = "https://jj-vcs.github.io/jj/latest/config-schema.json"
Copy link
Member

Choose a reason for hiding this comment

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

Ideally, users would be able to target the version of the tool they have, but that's probably not always possible (i.e. git compiled versions?) We could figure that out later on, in any case!

Copy link
Author

Choose a reason for hiding this comment

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

Once we have it deployed for a tagged release we can start updating to use the version (the same way the rest of the docs are versioned), it just won't work for any versions prior (unless we have a system for back porting that kind of thing?).

```

### Fixed bugs

* Fixed diff selection by external tools with `jj split`/`commit -i FILESETS`.
Expand Down
1 change: 1 addition & 0 deletions docs/config-schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
../cli/src/config-schema.json
40 changes: 40 additions & 0 deletions docs/config.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,12 +23,17 @@ These are listed in the order they are loaded; the settings from earlier items
in the list are overridden by the settings from later items if they disagree.
Every type of config except for the built-in settings is optional.

You can enable JSON Schema validation in your editor by adding a `$schema`
reference at the top of your TOML config files. See [JSON Schema
Support] for details.

See the [TOML site] and the [syntax guide] for a detailed description of the
syntax. We cover some of the basics below.

[the user config file]: #user-config-file
[TOML site]: https://toml.io/en/
[syntax guide]: https://toml.io/en/v1.0.0
[JSON Schema Support]: #json-schema-support

The first thing to remember is that the value of a setting (the part to the
right of the `=` sign) should be surrounded in quotes if it's a string.
Expand Down Expand Up @@ -1253,6 +1258,41 @@ default locations. For example,
env JJ_CONFIG=/dev/null jj log # Ignores any settings specified in the config file.
```

### JSON Schema Support

Many popular editors support TOML file syntax highlighting and validation. To
enable schema validation in your editor, add this line at the top of your TOML
config files:

```toml
"$schema" = "https://jj-vcs.github.io/jj/latest/config-schema.json"
```

This enables features like:

- Autocomplete for config keys
- Type checking of values
- Documentation on hover
- Validation of settings

Here are some popular editors with TOML schema validation support:

- VS Code
- Install [Even Better TOML](https://marketplace.visualstudio.com/items?itemName=tamasfe.even-better-toml)

- Neovim/Vim
- Use with [nvim-lspconfig](https://github.com/neovim/nvim-lspconfig) and [taplo](https://github.com/tamasfe/taplo)

- JetBrains IDEs (IntelliJ, PyCharm, etc)
- Install [TOML](https://plugins.jetbrains.com/plugin/8195-toml) plugin

- Sublime Text
- Install [LSP](https://packagecontrol.io/packages/LSP) and [LSP-taplo](https://packagecontrol.io/packages/LSP-taplo)

- Emacs
- Install [lsp-mode](https://github.com/emacs-lsp/lsp-mode) and [toml-mode](https://github.com/dryman/toml-mode.el)
- Configure [taplo](https://github.com/tamasfe/taplo) as the LSP server

### Specifying config on the command-line

You can use one or more `--config`/`--config-file` options on the command line
Expand Down