Nvim documentation: pi_health

main help file
*pi_health.txt*   Healthcheck framework

Author: TJ DeVries <[email protected]> 

                                      Type |gO| to see the table of contents.

==============================================================================

Introduction                            *health*

health.vim is a minimal framework to help with troubleshooting user
configuration. Nvim ships with healthchecks for configuration, performance,
python support, ruby support, clipboard support, and more.

To run the healthchecks, use this command:

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

==============================================================================

Commands                                *health-commands*


                                        *:checkhealth* *:CheckHealth*
:checkhealth          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.

:checkhealth {plugins}
                Run healthcheck(s) for one or more plugins. E.g. to run only
                the standard Nvim healthcheck:
                        :checkhealth nvim
 
                To run the healthchecks for the "foo" and "bar" plugins
                (assuming these plugins are on 'runtimepath' or 'packpath' and
                they have implemented the Lua or Vimscript interface
                require("foo.health").check() and health#bar#check(),
                respectively):
                        :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` 
                        :checkhealth vim.lsp vim.treesitter
                        :checkhealth vim*
 
==============================================================================

Lua Functions                           *health-functions-lua* *health-lua*

The Lua "health" module can be used to create new healthchecks (see also
|health-functions-vim|). To get started, simply use: 
        local health = require('health')
 

health.report_start({name})                             *health.report_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.


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


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


health.report_warn({msg} [, {advice}])                  *health.report_warn()*
        Reports a warning. {advice} is an optional List of suggestions.


health.report_error({msg} [, {advice}])                 *health.report_error()*
        Reports an error. {advice} is an optional List of suggestions.

==============================================================================

Create a Lua healthcheck                *health-dev-lua*

Healthchecks are functions that check the user environment, configuration,
etc. Nvim has built-in healthchecks in $VIMRUNTIME/autoload/health/.

To add a new healthcheck for your own plugin, simply define a Lua module in
your plugin that returns a table with a "check()" function. |:checkhealth|
will automatically find and invoke this function.

If your plugin is named "foo", then its healthcheck module should be a file in
one of these locations on 'runtimepath' or 'packpath':
        - lua/foo/health/init.lua
        - lua/foo/health.lua

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

All submodules should return a Lua table containing the method `check()`.

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

        local M = {}
        local health = require("health")

        M.check = function()
          health.report_start("my_plugin report")
          -- make sure setup function parameters are ok
          if check_setup() then
            health.report_ok("Setup function is correct")
          else
            health.report_error("Setup function is incorrect")
          end
          -- do some more checking
          -- ...
        end

        return M

==============================================================================

Vimscript Functions             *health-functions-vimscript* *health-vimscript*

health.vim functions are for creating new healthchecks. (See also
|health-functions-lua|)


health#report_start({name})                             *health#report_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.


health#report_info({msg})                               *health#report_info*
        Reports an informational message.


health#report_ok({msg})                                 *health#report_ok*
        Reports a "success" message.


health#report_warn({msg} [, {advice}])                  *health#report_warn*
        Reports a warning. {advice} is an optional List of suggestions.


health#report_error({msg} [, {advice}])                 *health#report_error*
        Reports an error. {advice} is an optional List of suggestions.


health#{plugin}#check()                                 *health.user_checker*
        Healthcheck function for {plugin}. Called by |:checkhealth|
        automatically. Example:

        function! health#my_plug#check() abort
          silent call s:check_environment_vars()
          silent call s:check_python_configuration()
        endfunction
 
==============================================================================

Create a healthcheck                    *health-dev-vim*

Healthchecks are functions that check the user environment, configuration,
etc. Nvim has built-in healthchecks in $VIMRUNTIME/autoload/health/.

To add a new healthcheck for your own plugin, simply define a
health#{plugin}#check() function in autoload/health/{plugin}.vim.
|:checkhealth| automatically finds and invokes such functions.

If your plugin is named "foo", then its healthcheck function must be
        health#foo#check()

defined in this file on 'runtimepath' or 'packpath':
        - autoload/health/foo.vim

Copy this sample code into autoload/health/foo.vim and replace "foo" with your
plugin name:
        function! health#foo#check() abort
          call health#report_start('sanity checks')
          " perform arbitrary checks
          " ...
        
          if looks_good
            call health#report_ok('found required dependencies')
          else
            call health#report_error('cannot find foo', 
              \ ['npm install --save foo'])
          endif
        endfunction

top - main help file