vsg-bridge-ls/doc/configuration.md

2.2 KiB

Bridge configuration

The bridge loads optional TOML configuration in this order:

  1. $XDG_CONFIG_HOME/vsg-bridge-ls/config.toml, or ~/.config/vsg-bridge-ls/config.toml when XDG_CONFIG_HOME is unset;
  2. vsg-bridge-ls.toml in the process working directory;
  3. explicit command-line options.

Each later layer overrides values explicitly set by an earlier layer. Missing files are ignored. An unreadable file, invalid TOML, or unknown key stops startup with the responsible path instead of silently using unexpected settings.

To create the project file without copying an example from the documentation, run vsg-bridge-ls --write-config in the project directory. Other options on that invocation are written into the new file. Existing files are never overwritten.

vsg_configuration = ["/absolute/path/to/vsg.yaml"]
allow_browser_action = false
experimental_rule_fix = false
experimental_multi_rule_line_fix = false
debug_mode = false
disable_hover = false
strict_diagnostic_severity = false

The project file can explicitly set a Boolean to false to disable a setting enabled in the user file. A command-line Boolean flag enables its setting over both files. One or more command-line --configuration PATH values replace the complete vsg_configuration list from TOML.

allow_browser_action is disabled by default because the corresponding code action asks the LSP client to open an external HTTPS URL. It is equivalent to the explicit --allow-browser-action flag. Documentation URLs remain visible in diagnostics and hover when browser actions are disabled.

disable_hover is useful when another language server should own hover presentation. Setting it to true stops the bridge from advertising or returning hover text without disabling diagnostics, formatting, or actions. It is equivalent to --disable-hover.

strict_diagnostic_severity is disabled by default. In the default editor-friendly mode, VSG error findings become LSP warnings and VSG warning findings become LSP information; informational findings remain information. Syntax failures always remain LSP errors. Set this option to true, or pass --strict-diagnostic-severity, to map VSG lint severities to their matching LSP levels without demotion.