mirror of
https://github.com/neovim/neovim
synced 2025-07-16 01:01:49 +00:00
63323a9c81
Problem: `FileType` event is fired before checkhealth report is finished, so user can't override report settings or contents. https://github.com/neovim/neovim/pull/33172#issuecomment-2833513916 Solution: - Trigger FileType event later. - Document how to remove emojis.
161 lines
5.5 KiB
Plaintext
161 lines
5.5 KiB
Plaintext
*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' }
|
|
|
|
|
|
Local configuration:
|
|
|
|
Checkhealth sets its buffer filetype to "checkhealth". You can customize the
|
|
buffer by handling the |FileType| event. For example if you don't want emojis
|
|
in the health report: >vim
|
|
autocmd FileType checkhealth :set modifiable | silent! %s/\v( ?[^\x00-\x7F])//g
|
|
<
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
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:
|