cljoly/minimal-format.nvim Github stars for minimal-format.nvim

A simple & powerful formatting plugin that extends neovim just a little bit to automatically format your code.

  • Native: uses the formatprg setting, the setting used by the gq mapping in default vim.
  • Safe:
    • Doesn’t replace your code with garbage if the formatting command fails (unlike gq)
    • Applies the minimum difference required to the buffer. This means that the whole buffer won’t be changed and marks and external marks (used e.g. for diagnostics) will be preserved. This makes formatting less disruptive to your workflow
  • Asynchronous: neovim won’t hang while the formatting command is running
  • Can be configured to trigger automatically on write, per buffer
  • No startup cost: call the functions you need when you need them, no need to load anything during startup.

Getting started

Install this package with your favorite package manager.

Then, you can configure some mappings or user commands to the following functions:

  • require("minimal-format").format_with_formatprg(bufnr): format the buffer number bufnr
  • require("minimal-format").toggle_autocmd: toggle automatic formatting on write

Setting Up a Mapping to Format the Current File

Add the following to your init.lua:

vim.keymap.set("n", "<space>f", function()
  require("minimal-format").format_with_formatprg(0, false)
end, { desc = "Format current buffer, using formatprg when possible" })

Setting a Formatter per File Type

Configure formatprg like you normally would to use gq. For instance, it might look like this for C:

if executable('clang-format')
  setlocal formatprg=clang-format\ --assume-filename=a.c
  let b:undo_ftplugin .= ' fp<'

Paste the above snippet in .config/nvim/ftplugin/c.vim. Then when you call require("minimal-format").format_with_formatprg(0), the current buffer will be asynchronously formatted with this command.

Per Buffer Settings

Example for Rust, in .config/nvim/ftplugin/rust.lua, where we automatically detect the rust edition:

if vim.fn.executable "rustfmt" then
  vim.opt_local.formatprg = "rustfmt -q --emit=stdout"
  local edition = require("cj.rust").find_rust_edition()
  if edition then
    vim.opt_local.formatprg:append(" --edition " .. edition)
  vim.b.undo_ftplugin = vim.b.undo_ftplugin .. "|setl fp<"


where find_rust_edition is defined like this:

function M.find_rust_edition()
  local manifests = find_cargotoml()
  for _, manifest in ipairs(manifests) do
    local grep_output =
      vim.fn.system { "grep", "-E", "--only-matching", [[edition *= *"(\d+)"]], manifest }
    local year = vim.fn.substitute(grep_output or "", [[^.*"\(\d\+\)".*$]], [[\1]], "")
    if year ~= "" then
      return tonumber(year)
  return nil

Automatic formatting on save

The last option is to enable automatic formatting before writing a buffer.


if vim.fn.executable "stylua" then
  vim.opt_local.formatprg = "stylua -"
  vim.b.undo_ftplugin = vim.b.undo_ftplugin .. " fp<"



if executable('stylua')
  setlocal formatprg=stylua\ -
  let b:undo_ftplugin .= ' fp<'

  call v:lua.require'minimal-format'.enable_autocmd(0)

Example Formatters per Language

Cclang-format –assume-filename=a.c
Gawkgawk –pretty-print=- -f -
Luastylua -
Pythonblack -t py36 -q -
Rustrustfmt –quiet –emit=stdout
Tomltaplo fmt -