Quick links: help overview · quick reference · user manual toc · reference manual toc
pi_health.txt   Healthcheck framework

Author: TJ DeVries <devries.timothyj@gmail.com>

                                      Type gO to see the table of contents.

==============================================================================
Introduction                            health

health.vim 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: 

        :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 they are on 'runtimepath' and they have implemented
                the Lua require("foo.health").check() interface): 
                        :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*

==============================================================================
Functions                               health-functions vim.health

The Lua "health" module can be used to create new healthchecks. To get started
see health-dev.

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

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

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

vim.health.report_warn({msg} [, {advice}])              vim.health.report_warn()
        Reports a warning. {advice} is an optional list of suggestions to
        present to the user.

vim.health.report_error({msg} [, {advice}])             vim.health.report_error()
        Reports an error. {advice} is an optional list of suggestions to
        present to the user.

==============================================================================
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: 

        local M = {}

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

        return M


vim:et:tw=78:ts=8:ft=help:fdm=marker


Quick links: help overview · quick reference · user manual toc · reference manual toc