Complete reference docs for config options #879
Comments
|
Related: Even from reading the code it's hard to get a complete notion of the supported schema. You can find a few details in https://github.com/martinvonz/jj/blob/main/src/config.rs but I found info about how |
|
If you'd like, you could document what you have figured out. Your example from #878 (comment) might work well in the docs. |
|
I had no idea we had aliases already before I read that :) |
|
Also, |
Yes! I'd just like to make sure that we don't put UI-specific knowledge in the library crate as a result, and that we make it possible for custom |
|
Well, I put together a sketch of a JSON schema spec for jj config, but I'm not sure if I should send a PR directly to https://github.com/SchemaStore/schemastore/pulls or maybe stage a copy of it somewhere in the jj repo first. WDYT? With that installed, taplo LSP (in vim, VS Code, etc) give nice hints about what section names and properties are supported, so there's not such an urgent need for thorough reference docs on the config format. |
|
I had never heard of SchemaStore before. I don't mind if you send them a PR, but I don't know what their policy is for accepting PRs. Would we send them a PR to update the schema roughly once per minor release (i.e. jj 0.7.0 next time) or what do you think? |
|
They seem to accept pretty much whatever. Lots of JSON validators and LSPs are hooked up to use schemas from there (and apparently also TOML ones like taplo).
Right, I don't think there'd be much difficulty updating it in SchemaStore as often as needed, but did wonder if somehow keeping it in the same repo would be more convenient. The only thing is it seems more awkward hooking up to user tools if it lives elsewhere (maybe impossible for some tools?). |
|
Would it help if we had a command to print that JSON format? Maybe that could be |
|
I think it wouldn't because the schema needs to be tied to a public ID (a URL basically), and hooking up to any copy that's only stored locally involves extra steps. It might be worth just storing a copy in this repo (so we're more likely to remember to update it when adding new supported config options) but copy it over to SchemaStore via PRs there as well. Maybe that could even be automated. Not sure the best model for if there are additional config options available internally at Google. It's not the end of the world if those have to be looked up manually and aren't as nicely integrated into auto-suggest, but hopefully in that special case there'd be a way to overlay a forked internal schema for googlers without too much manual setup for each user. |
|
So I think it's best to start with checking it into this repo and then figure out where it should be hosted longer term. If you can suggest a file path and a URL we could reserve for it, I can send a PR and we can follow up on the other stuff later. Another advantage of having it available to the jj code is it could be used for introspection, user-friendly validation messages, and maybe some kind of generated reference docs. |
Thanks. I agree. For the file, I'd go with
Yes! Mercurial has a central config registration for the same reasons. We could also use it for shell completion some day, but I generally consider that blocked by clap-rs/clap#1232. |
Can be used with tools like taplo-lsp to show hints & validation in editors/IDEs. Won't apply automatically to config files until it's submitted to schemastore.org, but in the meantime it can be used via a schema directive (https://taplo.tamasfe.dev/configuration/directives.html#the-schema-directive) or other manual config mechanism. Context in #879.
Can be used with tools like taplo-lsp to show hints & validation in editors/IDEs. Won't apply automatically to config files until it's submitted to schemastore.org, but in the meantime it can be used via a schema directive (https://taplo.tamasfe.dev/configuration/directives.html#the-schema-directive) or other manual config mechanism. Context in #879.
Can be used with tools like taplo-lsp to show hints & validation in editors/IDEs. Won't apply automatically to config files until it's submitted to schemastore.org, but in the meantime it can be used via a schema directive (https://taplo.tamasfe.dev/configuration/directives.html#the-schema-directive) or other manual config mechanism. Context in #879.
Can be used with tools like taplo-lsp to show hints & validation in editors/IDEs. Won't apply automatically to config files until it's submitted to schemastore.org, but in the meantime it can be used via a schema directive (https://taplo.tamasfe.dev/configuration/directives.html#the-schema-directive) or other manual config mechanism. Context in #879.
Can be used with tools like taplo-lsp to show hints & validation in editors/IDEs. Won't apply automatically to config files until it's submitted to schemastore.org, but in the meantime it can be used via a schema directive (https://taplo.tamasfe.dev/configuration/directives.html#the-schema-directive) or other manual config mechanism. Context in #879.
There's a doc on configs with some info/examples, but it doesn't seem to list every supported config option. For example, I couldn't find the
[alias]section mentioned anywhere in there. Could there be a complete reference doc somewhere?And/or the schema were explicitly captured somewhere (in something like schemastore.org but for TOML, that could be hooked up to editor integrations).
The text was updated successfully, but these errors were encountered: