Home Original page

GitHub - nvimdev/guard.nvim: Lightweight, fast and async formatting and linting plugin for Neovim

LuaRocks GitHub Actions Workflow Status GitHub Actions Workflow Status

Async formatting and linting utility for neovim 0.10+.

Features

  • Async and blazingly fast
  • Builtin support for popular formatters and linters
  • Minimal API allowing for full customization
  • Light-weight

TLDR

help guard.nvim-tldr

  • Install with your favorite package manager
  • Register formatters:
local ft = require('guard.filetype')
ft('c'):fmt('clang-format')
formatter-demo-nosound.mp4
  • Register linters
local ft = require('guard.filetype')
ft('lua'):lint('selene')
linter-demo-nosound.mp4
  • They can also be chained together:
local ft = require('guard.filetype')
ft('haskell'):fmt('ormolu')
             :lint('hlint')
  • Formatters and linters can also be chained:
local ft = require('guard.filetype')
ft('python'):fmt('isort')
            :append('black')
            :lint('mypy')
            :append('mypyc')
            :append('dmypy')
  • You can register the same formatter for multiple filetypes:
local ft = require('guard.filetype')
ft('typescript,javascript,typescriptreact'):fmt('prettier')
  • Lint all your files with codespell
-- this does not work with formatters
ft('*'):lint('codespell')
  • Custom formatters:
-- always use 4 spaces for c files
ft('c'):fmt({
    cmd = "clang-format",
    args = { "--style={IndentWidth: 4}" },
    stdin = true,
})

Usage

help guard.nvim-usage

Some presets can be configured via vim.g.guard_config

-- defaults
vim.g.guard_config = {
    -- format on write to buffer
    fmt_on_save = true,
    -- use lsp if no formatter was defined for this filetype
    lsp_as_default_formatter = false,
    -- whether or not to save the buffer after formatting
    save_on_fmt = true,
    -- automatic linting
    auto_lint = true,
    -- how frequently can linters be called
    lint_interval = 500
    -- show diagnostic after format done
    refresh_diagnostic = true,
    -- always save file after call Guard fmt
    always_save = false,
}

Here are all the Guard subcommands

Name Desc
Guard fmt Manually call format, also works with visual mode (best effort range formatting)
Guard lint Manually request for lint
Guard enable-fmt Turns auto formatting on for the current buffer
Guard disable-fmt Turns auto formatting off for the current buffer
Guard enable-lint Turns linting on for the current buffer
Guard disable-lint Turns linting off for the current buffer

Further configuration

You can easily create your own configuration that's not in guard-collection, see help guard.nvim-creating-new-configurations.

For more niche use cases, help guard.nvim-advanced-tips demonstrates how to:

  • Write your own formatting logic using the fn field.
  • Write your own linting logic using the fn field.
  • Leverage guard's autocmds to create a formatting status indicator.
  • Creating a dynamic formatter that respects neovom tab/space settings.