neovim/runtime/doc/health.txt

*health.txt*               Nvim


                 NVIM REFERENCE MANUAL


                                       Type |gO| to see the table of contents.

==============================================================================
Checkhealth                                              *vim.health* *health*


vim.health is a minimal framework to help users troubleshoot configuration and
any other environment conditions that a plugin might care about. Nvim ships
with healthchecks for configuration, performance, python support, ruby
support, clipboard support, and more.

To run all healthchecks, use: >vim

        :checkhealth
<
Plugin authors are encouraged to write new healthchecks. |health-dev|

COMMANDS                                                     *health-commands*

                                                           *:che* *:checkhealth*
:che[ckhealth]  Run all healthchecks.
                                                                       *E5009*
                Nvim depends on |$VIMRUNTIME|, 'runtimepath' and 'packpath' to
                find the standard "runtime files" for syntax highlighting,
                filetype-specific behavior, and standard plugins (including
                :checkhealth).  If the runtime files cannot be found then
                those features will not work.

:che[ckhealth] {plugins}
                Run healthcheck(s) for one or more plugins. E.g. to run only
                the standard Nvim healthcheck: >vim
                        :checkhealth vim.health
<
                To run the healthchecks for the "foo" and "bar" plugins
                (assuming they are on 'runtimepath' and they have implemented
                the Lua `require("foo.health").check()` interface): >vim
                        :checkhealth foo bar
<
                To run healthchecks for Lua submodules, use dot notation or
                "*" to refer to all submodules. For example Nvim provides
                `vim.lsp` and `vim.treesitter`:  >vim
                        :checkhealth vim.lsp vim.treesitter
                        :checkhealth vim*
<

USAGE                                                           *health-usage*

Local mappings in the healthcheck buffer:

q               Closes the window.

Global configuration:

                                                                    *g:health*
g:health  Dictionary with the following optional keys:
          - `style` (`'float'|nil`) Set to "float" to display :checkhealth in
          a floating window instead of the default behavior.

          Example: >lua
            vim.g.health = { style = 'float' }

--------------------------------------------------------------------------------
Create a healthcheck                                              *health-dev*

Healthchecks are functions that check the user environment, configuration, or
any other prerequisites that a plugin cares about. Nvim ships with
healthchecks in:
        - $VIMRUNTIME/autoload/health/
        - $VIMRUNTIME/lua/vim/lsp/health.lua
        - $VIMRUNTIME/lua/vim/treesitter/health.lua
        - and more...

To add a new healthcheck for your own plugin, simply create a "health.lua"
module on 'runtimepath' that returns a table with a "check()" function. Then
|:checkhealth| will automatically find and invoke the function.

For example if your plugin is named "foo", define your healthcheck module at
one of these locations (on 'runtimepath'):
        - lua/foo/health/init.lua
        - lua/foo/health.lua

If your plugin also provides a submodule named "bar" for which you want
a separate healthcheck, define the healthcheck at one of these locations:
        - lua/foo/bar/health/init.lua
        - lua/foo/bar/health.lua

All such health modules must return a Lua table containing a `check()`
function.

Copy this sample code into `lua/foo/health.lua`, replacing "foo" in the path
with your plugin name: >lua

        local M = {}

        M.check = function()
          vim.health.start("foo report")
          -- make sure setup function parameters are ok
          if check_setup() then
            vim.health.ok("Setup is correct")
          else
            vim.health.error("Setup is incorrect")
          end
          -- do some more checking
          -- ...
        end

        return M


error({msg}, {...})                                       *vim.health.error()*
    Reports an error.

    Parameters: ~
      • {msg}  (`string`)
      • {...}  (`string|string[]`) Optional advice

info({msg})                                                *vim.health.info()*
    Reports an informational message.

    Parameters: ~
      • {msg}  (`string`)

ok({msg})                                                    *vim.health.ok()*
    Reports a "success" message.

    Parameters: ~
      • {msg}  (`string`)

start({name})                                             *vim.health.start()*
    Starts a new report. Most plugins should call this only once, but if you
    want different sections to appear in your report, call this once per
    section.

    Parameters: ~
      • {name}  (`string`)

warn({msg}, {...})                                         *vim.health.warn()*
    Reports a warning.

    Parameters: ~
      • {msg}  (`string`)
      • {...}  (`string|string[]`) Optional advice


 vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl: