Nvim :help
pages, generated
from source
using the tree-sitter-vimdoc parser.
{namespace}
as their first argument, while those for
consumers generally do not require a namespace (though often one may be
optionally supplied). A good rule of thumb is that if a method is meant to
modify the diagnostics for a buffer (e.g. vim.diagnostic.set()) then it
requires a namespace.vim.diagnostic.severity
diagnostic-severity
The "severity" key in a diagnostic is one of the values defined in
vim.diagnostic.severity
:vim.diagnostic.get(0, { severity = vim.diagnostic.severity.WARN })
2. A table with a "min" or "max" key (or both):vim.diagnostic.get(0, { severity = { min = vim.diagnostic.severity.WARN } })
vim.diagnostic.get(0, { severity = {
vim.diagnostic.severity.WARN,
vim.diagnostic.severity.INFO,
} })
function(namespace, bufnr, diagnostics, opts)
function(namespace, bufnr)
vim.diagnostic.handlers
(see
diagnostic-handlers-example).{opts}
table passed to a handler is the full set of configuration options
(that is, it is not limited to just the options for the handler itself). The
values in the table are already resolved (i.e. if a user specifies a
function for a config option, the function has already been evaluated).diagnostic-handlers-example
The example below creates a new handler that notifies the user of diagnostics
with vim.notify():-- It's good practice to namespace custom handlers to avoid collisions
vim.diagnostic.handlers["my/notify"] = {
show = function(namespace, bufnr, diagnostics, opts)
-- In our example, the opts table has a "log_level" option
local level = opts["my/notify"].log_level
local name = vim.diagnostic.get_namespace(namespace).name
local msg = string.format("%d diagnostics in buffer %d from %s",
#diagnostics,
bufnr,
name)
vim.notify(msg, level)
end,
}
-- Users can configure the handler
vim.diagnostic.config({
["my/notify"] = {
log_level = vim.log.levels.INFO
}
})
-- Create a custom namespace. This will aggregate signs from all other
-- namespaces and only show the one with the highest severity on a
-- given line
local ns = vim.api.nvim_create_namespace("my_namespace")
-- Get a reference to the original signs handler
local orig_signs_handler = vim.diagnostic.handlers.signs
-- Override the built-in signs handler
vim.diagnostic.handlers.signs = {
show = function(_, bufnr, _, opts)
-- Get all diagnostics from the whole buffer rather than just the
-- diagnostics passed to the handler
local diagnostics = vim.diagnostic.get(bufnr)
-- Find the "worst" diagnostic per line
local max_severity_per_line = {}
for _, d in pairs(diagnostics) do
local m = max_severity_per_line[d.lnum]
if not m or d.severity < m.severity then
max_severity_per_line[d.lnum] = d
end
end
-- Pass the filtered diagnostics (with our custom namespace) to
-- the original handler
local filtered_diagnostics = vim.tbl_values(max_severity_per_line)
orig_signs_handler.show(ns, bufnr, filtered_diagnostics, opts)
end,
hide = function(_, bufnr)
orig_signs_handler.hide(ns, bufnr)
end,
}
Diagnostic
followed by
the type of highlight (e.g., Sign
, Underline
, etc.) and the severity (e.g.
Error
, Warn
, etc.)highlight DiagnosticError guifg="BrightRed"
hl-DiagnosticError
DiagnosticError
Used as the base highlight group.
Other Diagnostic highlights link to this by default (except Underline)hl-DiagnosticWarn
DiagnosticWarn
Used as the base highlight group.
Other Diagnostic highlights link to this by default (except Underline)hl-DiagnosticInfo
DiagnosticInfo
Used as the base highlight group.
Other Diagnostic highlights link to this by default (except Underline)hl-DiagnosticHint
DiagnosticHint
Used as the base highlight group.
Other Diagnostic highlights link to this by default (except Underline)hl-DiagnosticOk
DiagnosticOk
Used as the base highlight group.
Other Diagnostic highlights link to this by default (except Underline)hl-DiagnosticVirtualTextError
DiagnosticVirtualTextError
Used for "Error" diagnostic virtual text.hl-DiagnosticVirtualTextWarn
DiagnosticVirtualTextWarn
Used for "Warn" diagnostic virtual text.hl-DiagnosticVirtualTextInfo
DiagnosticVirtualTextInfo
Used for "Info" diagnostic virtual text.hl-DiagnosticVirtualTextHint
DiagnosticVirtualTextHint
Used for "Hint" diagnostic virtual text.hl-DiagnosticVirtualTextOk
DiagnosticVirtualTextOk
Used for "Ok" diagnostic virtual text.hl-DiagnosticUnderlineError
DiagnosticUnderlineError
Used to underline "Error" diagnostics.hl-DiagnosticUnderlineWarn
DiagnosticUnderlineWarn
Used to underline "Warn" diagnostics.hl-DiagnosticUnderlineInfo
DiagnosticUnderlineInfo
Used to underline "Info" diagnostics.hl-DiagnosticUnderlineHint
DiagnosticUnderlineHint
Used to underline "Hint" diagnostics.hl-DiagnosticUnderlineOk
DiagnosticUnderlineOk
Used to underline "Ok" diagnostics.hl-DiagnosticFloatingError
DiagnosticFloatingError
Used to color "Error" diagnostic messages in diagnostics float.
See vim.diagnostic.open_float()hl-DiagnosticFloatingWarn
DiagnosticFloatingWarn
Used to color "Warn" diagnostic messages in diagnostics float.hl-DiagnosticFloatingInfo
DiagnosticFloatingInfo
Used to color "Info" diagnostic messages in diagnostics float.hl-DiagnosticFloatingHint
DiagnosticFloatingHint
Used to color "Hint" diagnostic messages in diagnostics float.hl-DiagnosticFloatingOk
DiagnosticFloatingOk
Used to color "Ok" diagnostic messages in diagnostics float.hl-DiagnosticSignError
DiagnosticSignError
Used for "Error" signs in sign column.hl-DiagnosticSignWarn
DiagnosticSignWarn
Used for "Warn" signs in sign column.hl-DiagnosticSignInfo
DiagnosticSignInfo
Used for "Info" signs in sign column.hl-DiagnosticSignHint
DiagnosticSignHint
Used for "Hint" signs in sign column.hl-DiagnosticSignOk
DiagnosticSignOk
Used for "Ok" signs in sign column.hl-DiagnosticDeprecated
DiagnosticDeprecated
Used for deprecated or obsolete code.hl-DiagnosticUnnecessary
DiagnosticUnnecessary
Used for unnecessary or unused code.-- Highlight entire line for errors
-- Highlight the line number for warnings
vim.diagnostic.config({
signs = {
text = {
[vim.diagnostic.severity.ERROR] = '',
[vim.diagnostic.severity.WARN] = '',
},
linehl = {
[vim.diagnostic.severity.ERROR] = 'ErrorMsg',
},
numhl = {
[vim.diagnostic.severity.WARN] = 'WarningMsg',
},
},
})
When the "severity_sort" option is set (see vim.diagnostic.config()) the
priority of each sign depends on the severity of the associated diagnostic.
Otherwise, all signs have the same priority (the value of the "priority"
option in the "signs" table of vim.diagnostic.config() or 10 if unset).DiagnosticChanged
DiagnosticChanged After diagnostics have changed. When used from Lua,
the new diagnostics are passed to the autocmd
callback in the "data" table.vim.api.nvim_create_autocmd('DiagnosticChanged', {
callback = function(args)
local diagnostics = args.data.diagnostics
vim.print(diagnostics)
end,
})
{bufnr}
(integer
) Buffer number
{lnum}
(integer
) The starting line of the diagnostic
(0-indexed)
{end_lnum}
(integer
) The final line of the diagnostic (0-indexed)
{col}
(integer
) The starting column of the diagnostic
(0-indexed)
{end_col}
(integer
) The final column of the diagnostic
(0-indexed)
{message}
(string
) The diagnostic text
{source}
(string
) The source of the diagnostic
{code}
(string|integer
) The diagnostic code
{_tags}
({ deprecated: boolean, unnecessary: boolean}
)
{user_data}
(any
) arbitrary data plugins can add
{namespace}
(integer
)
vim.diagnostic.GetOpts
A table with the following keys:{namespace}
(integer[]|integer
) Limit diagnostics to one or more
namespaces.
{lnum}
(integer
) Limit diagnostics to those spanning the
specified line number.
{cursor_position}
({[1]:integer,[2]:integer}
, default: current cursor position)
Cursor position as a (row, col)
tuple. See
nvim_win_get_cursor().
{float}
(boolean|vim.diagnostic.Opts.Float
, default:
true
) If true
, call
vim.diagnostic.open_float() after moving. If a
table, pass the table as the {opts}
parameter to
vim.diagnostic.open_float(). Unless overridden,
the float will show diagnostics at the new cursor
position (as if "cursor" were passed to the
"scope" option).
{win_id}
(integer
, default: 0
) Window ID
{name}
(string
)
{user_data}
(table
)
{disabled}
(boolean
)
vim.diagnostic.Opts
Each of the configuration options below accepts one of the following:
false
: Disable this feature
true
: Enable this feature, use default settings.
table
: Enable this feature with overrides. Use an empty table to use
default values.
function
: Function with signature (namespace, bufnr) that returns any
of the above.
{underline}
(boolean|vim.diagnostic.Opts.Underline|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.Underline
, default: true
)
Use underline for diagnostics.
{virtual_text}
(boolean|vim.diagnostic.Opts.VirtualText|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.VirtualText
, default: true
)
Use virtual text for diagnostics. If multiple
diagnostics are set for a namespace, one prefix
per diagnostic + the last diagnostic message are
shown.
{signs}
(boolean|vim.diagnostic.Opts.Signs|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.Signs
, default: true
)
Use signs for diagnostics diagnostic-signs.
{float}
(boolean|vim.diagnostic.Opts.Float|fun(namespace: integer, bufnr:integer): vim.diagnostic.Opts.Float
)
Options for floating windows. See
vim.diagnostic.Opts.Float.
{update_in_insert}
(boolean
, default: false
) Update diagnostics
in Insert mode (if false
, diagnostics are
updated on InsertLeave)
{severity_sort}
(boolean|{reverse?:boolean}
, default: false
)
Sort diagnostics by severity. This affects the
order in which signs and virtual text are
displayed. When true, higher severities are
displayed before lower severities (e.g. ERROR is
displayed before WARN). Options:
{reverse}
(boolean) Reverse sort order
{bufnr}
(integer
, default: current buffer) Buffer number
to show diagnostics from.
{namespace}
(integer
) Limit diagnostics to the given namespace
{scope}
('line'|'buffer'|'cursor'|'c'|'l'|'b'
, default:
line
) Show diagnostics from the whole buffer
(buffer"
, the current cursor line (line
), or the
current cursor position (cursor
). Shorthand
versions are also accepted (c
for cursor
, l
for line
, b
for buffer
).
{pos}
(integer|{[1]:integer,[2]:integer}
) If {scope}
is
"line" or "cursor", use this position rather than
the cursor position. If a number, interpreted as a
line number; otherwise, a (row, col) tuple.
{severity_sort}
(boolean|{reverse?:boolean}
, default: false
)
Sort diagnostics by severity. Overrides the setting
from vim.diagnostic.config().
{severity}
(vim.diagnostic.SeverityFilter
) See
diagnostic-severity. Overrides the setting from
vim.diagnostic.config().
{header}
(string|{[1]:string,[2]:any}
) String to use as the
header for the floating window. If a table, it is
interpreted as a [text, hl_group]
tuple. Overrides
the setting from vim.diagnostic.config().
{source}
(boolean|'if_many'
) Include the diagnostic source
in the message. Use "if_many" to only show sources
if there is more than one source of diagnostics in
the buffer. Otherwise, any truthy value means to
always show the diagnostic source. Overrides the
setting from vim.diagnostic.config().
{format}
(fun(diagnostic:vim.Diagnostic): string
) A
function that takes a diagnostic as input and
returns a string. The return value is the text used
to display the diagnostic. Overrides the setting
from vim.diagnostic.config().
{prefix}
(string|table|(fun(diagnostic:vim.Diagnostic,i:integer,total:integer): string, string)
)
Prefix each diagnostic in the floating window:
function
, {i}
is the index of the
diagnostic being evaluated and {total}
is the
total number of diagnostics displayed in the
window. The function should return a string
which is prepended to each diagnostic in the
window as well as an (optional) highlight group
which will be used to highlight the prefix.
string
, it is prepended to each diagnostic
in the window with no highlight. Overrides the
setting from vim.diagnostic.config().
{suffix}
(string|table|(fun(diagnostic:vim.Diagnostic,i:integer,total:integer): string, string)
)
Same as {prefix}
, but appends the text to the
diagnostic instead of prepending it. Overrides the
setting from vim.diagnostic.config().
{focus_id}
(string
)
{severity}
(vim.diagnostic.SeverityFilter
) Only show virtual text
for diagnostics matching the given severity
diagnostic-severity
{priority}
(integer
, default: 10
) Base priority to use for
signs. When {severity_sort}
is used, the priority of a
sign is adjusted based on its severity. Otherwise, all
signs use the same priority.
{text}
(table<vim.diagnostic.Severity,string>
) A table mapping
diagnostic-severity to the sign text to display in the
sign column. The default is to use "E"
, "W"
, "I"
,
and "H"
for errors, warnings, information, and hints,
respectively. Example:vim.diagnostic.config({
signs = { text = { [vim.diagnostic.severity.ERROR] = 'E', ... } }
})
{numhl}
(table<vim.diagnostic.Severity,string>
) A table mapping
diagnostic-severity to the highlight group used for the
line number where the sign is placed.
{linehl}
(table<vim.diagnostic.Severity,string>
) A table mapping
diagnostic-severity to the highlight group used for the
whole line the sign is placed in.
{severity}
(vim.diagnostic.SeverityFilter
) Only underline
diagnostics matching the given severity
diagnostic-severity.
{severity}
(vim.diagnostic.SeverityFilter
) Only show
virtual text for diagnostics matching the given
severity diagnostic-severity
{source}
(boolean|"if_many"
) Include the diagnostic
source in virtual text. Use 'if_many'
to only
show sources if there is more than one
diagnostic source in the buffer. Otherwise, any
truthy value means to always show the diagnostic
source.
{spacing}
(integer
) Amount of empty spaces inserted at
the beginning of the virtual text.
{prefix}
(string|(fun(diagnostic:vim.Diagnostic,i:integer,total:integer): string)
)
Prepend diagnostic message with prefix. If a
function
, {i}
is the index of the diagnostic
being evaluated, and {total}
is the total number
of diagnostics for the line. This can be used to
render diagnostic symbols or error codes.
{suffix}
(string|(fun(diagnostic:vim.Diagnostic): string)
)
Append diagnostic message with suffix. This can
be used to render an LSP diagnostic error code.
{format}
(fun(diagnostic:vim.Diagnostic): string
) The
return value is the text used to display the
diagnostic. Example:function(diagnostic)
if diagnostic.severity == vim.diagnostic.severity.ERROR then
return string.format("E: %s", diagnostic.message)
end
return diagnostic.message
end
{opts}
, {namespace}
) vim.diagnostic.config()
Configure diagnostic options globally or for a specific diagnostic
namespace.vim.diagnostic.config({ virtual_text = true })
vim.diagnostic.set(ns, 0, diagnostics, { virtual_text = false })
{opts}
(vim.diagnostic.Opts?
) When omitted or nil
, retrieve
the current configuration. Otherwise, a configuration
table (see vim.diagnostic.Opts).
{namespace}
(integer?
) Update the options for the given namespace.
When omitted, update the global diagnostic options.
vim.diagnostic.Opts?
) Current diagnostic config if {opts}
is
omitted. See vim.diagnostic.Opts.{bufnr}
(integer?
) Buffer number to get diagnostics from. Use 0 for
current buffer or nil for all buffers.
table
) Table with actually present severity values as keys (see
diagnostic-severity) and integer counts as values.is_enabled()
:vim.diagnostic.enable(not vim.diagnostic.is_enabled())
{enable}
(boolean?
) true/nil to enable, false to disable
{ns_id}
(integer
) Diagnostic namespace, or nil
for
all.
{bufnr}
(integer
) Buffer number, or 0 for current
buffer, or nil
for all buffers.
{list}
) vim.diagnostic.fromqflist()
Convert a list of quickfix items to a list of diagnostics.{bufnr}
(integer?
) Buffer number to get diagnostics from. Use 0 for
current buffer or nil for all buffers.
vim.Diagnostic[]
) Fields bufnr
, end_lnum
, end_col
, and
severity
are guaranteed to be present. See vim.Diagnostic.{namespace}
) vim.diagnostic.get_namespace()
Get namespace metadata.{namespace}
(integer
) Diagnostic namespace
vim.diagnostic.get_namespaces()
Get current diagnostic namespaces.{opts}
) vim.diagnostic.get_next()
Get the next diagnostic closest to the cursor position.{opts}
) vim.diagnostic.get_next_pos()
Return the position of the next diagnostic in the current buffer.table|false
) Next diagnostic position as a (row, col)
tuple or
false if no next diagnostic.{opts}
) vim.diagnostic.get_prev()
Get the previous diagnostic closest to the cursor position.{opts}
) vim.diagnostic.get_prev_pos()
Return the position of the previous diagnostic in the current buffer.table|false
) Previous diagnostic position as a (row, col)
tuple
or false
if there is no prior diagnostic.{opts}
) vim.diagnostic.goto_next()
Move to the next diagnostic.{opts}
) vim.diagnostic.goto_prev()
Move to the previous diagnostic in the current buffer.{namespace}
(integer?
) Diagnostic namespace. When omitted, hide
diagnostics from all namespaces.
{bufnr}
(integer?
) Buffer number, or 0 for current buffer. When
omitted, hide diagnostics in all buffers.
{filter}
) vim.diagnostic.is_enabled()
Check whether diagnostics are enabled.{ns_id}
(integer
) Diagnostic namespace, or nil
for
all.
{bufnr}
(integer
) Buffer number, or 0 for current
buffer, or nil
for all buffers.
boolean
)vim.diagnostic.match()
match({str}
, {pat}
, {groups}
, {severity_map}
, {defaults}
)
Parse a diagnostic from a string.WARNING filename:27:3: Variable 'foo' does not exist
local s = "WARNING filename:27:3: Variable 'foo' does not exist"
local pattern = "^(%w+) %w+:(%d+):(%d+): (.+)$"
local groups = { "severity", "lnum", "col", "message" }
vim.diagnostic.match(s, pattern, groups, { WARNING = vim.diagnostic.WARN })
{str}
(string
) String to parse diagnostics from.
{pat}
(string
) Lua pattern with capture groups.
{groups}
(string[]
) List of fields in a vim.Diagnostic
structure to associate with captures from {pat}
.
{severity_map}
(table
) A table mapping the severity field from
{groups}
with an item from vim.diagnostic.severity.
{defaults}
(table?
) Table of default values for any fields not
listed in {groups}
. When omitted, numeric values
default to 0 and "severity" defaults to ERROR.
{opts}
) vim.diagnostic.open_float()
Show diagnostics in a floating window.integer?
) float_bufnr
(integer?
) win_id{namespace}
(integer?
) Diagnostic namespace. When omitted, remove
diagnostics from all namespaces.
{bufnr}
(integer?
) Remove diagnostics for the given buffer.
When omitted, diagnostics are removed for all buffers.
{namespace}
, {bufnr}
, {diagnostics}
, {opts}
) vim.diagnostic.set()
Set diagnostics for the given namespace and buffer.{namespace}
(integer
) The diagnostic namespace
{bufnr}
(integer
) Buffer number
{opts}
(vim.diagnostic.Opts?
) Display options to pass to
vim.diagnostic.show(). See vim.diagnostic.Opts.
{opts}
) vim.diagnostic.setloclist()
Add buffer diagnostics to the location list.{opts}
(table?
) Configuration table with the following keys:
{namespace}
(integer
) Only add diagnostics from the given
namespace.
{winnr}
(integer
, default: 0
) Window number to set
location list for.
{open}
(boolean
, default: true
) Open the location list
after setting.
{title}
(string
) Title of the location list. Defaults to
"Diagnostics".
{opts}
) vim.diagnostic.setqflist()
Add all diagnostics to the quickfix list.{opts}
(table?
) Configuration table with the following keys:
{namespace}
(integer
) Only add diagnostics from the given
namespace.
{open}
(boolean
, default: true
) Open quickfix list
after setting.
{title}
(string
) Title of quickfix list. Defaults to
"Diagnostics".
vim.diagnostic.show()
show({namespace}
, {bufnr}
, {diagnostics}
, {opts}
)
Display diagnostics for the given namespace and buffer.{namespace}
(integer?
) Diagnostic namespace. When omitted, show
diagnostics from all namespaces.
{bufnr}
(integer?
) Buffer number, or 0 for current buffer.
When omitted, show diagnostics in all buffers.
{diagnostics}
(vim.Diagnostic[]?
) The diagnostics to display. When
omitted, use the saved diagnostics for the given
namespace and buffer. This can be used to display a
list of diagnostics without saving them or to display
only a subset of diagnostics. May not be used when
{namespace}
or {bufnr}
is nil. See vim.Diagnostic.
{diagnostics}
) vim.diagnostic.toqflist()
Convert a list of diagnostics to a list of quickfix items that can be
passed to setqflist() or setloclist().