health.txt (5584B)
1 *health.txt* Nvim 2 3 4 NVIM REFERENCE MANUAL 5 6 7 Type |gO| to see the table of contents. 8 9 ============================================================================== 10 Checkhealth *vim.health* *health* 11 12 vim.health is a minimal framework to help users troubleshoot configuration and 13 any other environment conditions that a plugin might care about. Nvim ships 14 with healthchecks for configuration, performance, python support, ruby 15 support, clipboard support, and more. 16 17 To run all healthchecks, use: >vim 18 :checkhealth 19 < 20 21 Plugin authors are encouraged to write new healthchecks. |health-dev| 22 23 24 COMMANDS *health-commands* 25 26 *:che* *:checkhealth* 27 :che[ckhealth] Run all healthchecks. 28 *E5009* 29 Nvim depends on |$VIMRUNTIME|, 'runtimepath' and 'packpath' to 30 find the standard "runtime files" for syntax highlighting, 31 filetype-specific behavior, and standard plugins (including 32 :checkhealth). If the runtime files cannot be found then 33 those features will not work. 34 35 :che[ckhealth] {plugins} 36 Run healthcheck(s) for one or more plugins. E.g. to run only 37 the standard Nvim healthcheck: >vim 38 :checkhealth vim.health 39 < 40 To run the healthchecks for the "foo" and "bar" plugins 41 (assuming they are on 'runtimepath' and they have implemented 42 the Lua `require("foo.health").check()` interface): >vim 43 :checkhealth foo bar 44 < 45 To run healthchecks for Lua submodules, use dot notation or 46 "*" to refer to all submodules. For example Nvim provides 47 `vim.lsp` and `vim.treesitter`: >vim 48 :checkhealth vim.lsp vim.treesitter 49 :checkhealth vim* 50 < 51 52 USAGE *health-usage* 53 54 Local mappings in the healthcheck buffer: 55 56 q Closes the window. 57 58 Global configuration: 59 *g:health* 60 g:health Dictionary with the following optional keys: 61 - `style` (`'float'|nil`) Set to "float" to display :checkhealth in 62 a floating window instead of the default behavior. 63 64 Example: >lua 65 vim.g.health = { style = 'float' } 66 67 68 Local configuration: 69 70 Checkhealth sets its buffer filetype to "checkhealth". You can customize the 71 buffer by handling the |FileType| event. For example if you don't want emojis 72 in the health report: >vim 73 autocmd FileType checkhealth :set modifiable | silent! %s/\v( ?[^\x00-\x7F])//g 74 < 75 76 77 -------------------------------------------------------------------------------- 78 Create a healthcheck *health-dev* 79 80 Healthchecks are functions that check the user environment, configuration, or 81 any other prerequisites that a plugin cares about. Nvim ships with 82 healthchecks in: 83 • $VIMRUNTIME/autoload/health/ 84 • $VIMRUNTIME/lua/vim/lsp/health.lua 85 • $VIMRUNTIME/lua/vim/treesitter/health.lua 86 • and more... 87 88 To add a new healthcheck for your own plugin, simply create a "health.lua" 89 module on 'runtimepath' that returns a table with a "check()" function. Then 90 |:checkhealth| will automatically find and invoke the function. 91 92 For example if your plugin is named "foo", define your healthcheck module at 93 one of these locations (on 'runtimepath'): 94 • lua/foo/health/init.lua 95 • lua/foo/health.lua 96 97 If your plugin also provides a submodule named "bar" for which you want a 98 separate healthcheck, define the healthcheck at one of these locations: 99 • lua/foo/bar/health/init.lua 100 • lua/foo/bar/health.lua 101 102 All such health modules must return a Lua table containing a `check()` 103 function. 104 105 Copy this sample code into `lua/foo/health.lua`, replacing "foo" in the path 106 with your plugin name: >lua 107 local M = {} 108 109 M.check = function() 110 vim.health.start("foo report") 111 -- make sure setup function parameters are ok 112 if check_setup() then 113 vim.health.ok("Setup is correct") 114 else 115 vim.health.error("Setup is incorrect") 116 end 117 -- do some more checking 118 -- ... 119 end 120 121 return M 122 < 123 124 125 error({msg}, {...}) *vim.health.error()* 126 Reports an error. 127 128 Parameters: ~ 129 • {msg} (`string`) 130 • {...} (`string|string[]`) Optional advice 131 132 info({msg}) *vim.health.info()* 133 Reports an informational message. 134 135 Parameters: ~ 136 • {msg} (`string`) 137 138 ok({msg}) *vim.health.ok()* 139 Reports a "success" message. 140 141 Parameters: ~ 142 • {msg} (`string`) 143 144 start({name}) *vim.health.start()* 145 Starts a new report. Most plugins should call this only once, but if you 146 want different sections to appear in your report, call this once per 147 section. 148 149 Parameters: ~ 150 • {name} (`string`) 151 152 warn({msg}, {...}) *vim.health.warn()* 153 Reports a warning. 154 155 Parameters: ~ 156 • {msg} (`string`) 157 • {...} (`string|string[]`) Optional advice 158 159 160 vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl: