path: root/doc/conform.txt

*conform.txt*
*Conform* *conform* *conform.nvim*
--------------------------------------------------------------------------------
CONTENTS                                                        *conform-contents*

  1. Options                                                 |conform-options|
  2. Api                                                         |conform-api|
  3. Formatters                                           |conform-formatters|
  4. Autoformat                                           |conform-autoformat|

--------------------------------------------------------------------------------
OPTIONS                                                          *conform-options*

>lua
    require("conform").setup({
      -- Map of filetype to formatters
      formatters_by_ft = {
        lua = { "stylua" },
        -- Conform will run multiple formatters sequentially
        python = { "isort", "black" },
        -- Use a sub-list to run only the first available formatter
        javascript = { { "prettierd", "prettier" } },
        -- Use the "*" filetype to run formatters on all files.
        -- Note that if you use this, you may want to set lsp_fallback = "always"
        -- (see :help conform.format)
        ["*"] = { "trim_whitespace" },
      },
      -- If this is set, Conform will run the formatter on save.
      -- It will pass the table to conform.format().
      -- This can also be a function that returns the table.
      format_on_save = {
        -- I recommend these options. See :help conform.format for details.
        lsp_fallback = true,
        timeout_ms = 500,
      },
      -- If this is set, Conform will run the formatter asynchronously after save.
      -- It will pass the table to conform.format().
      -- This can also be a function that returns the table.
      format_after_save = {
        lsp_fallback = true,
      },
      -- Set the log level. Use `:ConformInfo` to see the location of the log file.
      log_level = vim.log.levels.ERROR,
      -- Conform will notify you when a formatter errors
      notify_on_error = true,
      -- Define custom formatters here
      formatters = {
        my_formatter = {
          -- This can be a string or a function that returns a string
          command = "my_cmd",
          -- OPTIONAL - all fields below this are optional
          -- A list of strings, or a function that returns a list of strings
          -- Return a single string instead to run the command in a shell
          args = { "--stdin-from-filename", "$FILENAME" },
          -- If the formatter supports range formatting, create the range arguments here
          range_args = function(ctx)
            return { "--line-start", ctx.range.start[1], "--line-end", ctx.range["end"][1] }
          end,
          -- Send file contents to stdin, read new contents from stdout (default true)
          -- When false, will create a temp file (will appear in "$FILENAME" args). The temp
          -- file is assumed to be modified in-place by the format command.
          stdin = true,
          -- A function that calculates the directory to run the command in
          cwd = require("conform.util").root_file({ ".editorconfig", "package.json" }),
          -- When cwd is not found, don't run the formatter (default false)
          require_cwd = true,
          -- When returns false, the formatter will not be used
          condition = function(ctx)
            return vim.fs.basename(ctx.filename) ~= "README.md"
          end,
          -- Exit codes that indicate success (default {0})
          exit_codes = { 0, 1 },
          -- Environment variables. This can also be a function that returns a table.
          env = {
            VAR = "value",
          },
        },
        -- These can also be a function that returns the formatter
        other_formatter = function()
          return {
            command = "my_cmd",
          }
        end,
      },
    })

    -- You can set formatters_by_ft and formatters directly
    require("conform").formatters_by_ft.lua = { "stylua" }
    require("conform").formatters.my_formatter = {
      command = "my_cmd",
    }
<

--------------------------------------------------------------------------------
API                                                                  *conform-api*

format({opts}, {callback}): boolean                               *conform.format*
    Format a buffer

    Parameters:
      {opts}     `nil|table`
          {timeout_ms}   `nil|integer` Time in milliseconds to block for
                         formatting. Defaults to 1000. No effect if async =
                         true.
          {bufnr}        `nil|integer` Format this buffer (default 0)
          {async}        `nil|boolean` If true the method won't block. Defaults
                         to false. If the buffer is modified before the
                         formatter completes, the formatting will be discarded.
          {formatters}   `nil|string[]` List of formatters to run. Defaults to
                         all formatters for the buffer filetype.
          {lsp_fallback} `nil|boolean|"always"` Attempt LSP formatting if no
                         formatters are available. Defaults to false. If
                         "always", will attempt LSP formatting even if
                         formatters are available (useful if you set formatters
                         for the "*" filetype)
          {quiet}        `nil|boolean` Don't show any notifications for warnings
                         or failures. Defaults to false.
          {range}        `nil|table` Range to format. Table must contain `start`
                         and `end` keys with {row, col} tuples using (1,0)
                         indexing. Defaults to current selection in visual mode
          {id}           `nil|integer` Passed to |vim.lsp.buf.format| when
                         lsp_fallback = true
          {name}         `nil|string` Passed to |vim.lsp.buf.format| when
                         lsp_fallback = true
          {filter}       `nil|fun(client: table): boolean` Passed to
                         |vim.lsp.buf.format| when lsp_fallback = true
      {callback} `nil|fun(err: nil|string)` Called once formatting has completed
    Returns:
      `boolean` True if any formatters were attempted

list_formatters({bufnr}): conform.FormatterInfo[]        *conform.list_formatters*
    Retrieve the available formatters for a buffer

    Parameters:
      {bufnr} `nil|integer`

list_all_formatters(): conform.FormatterInfo[]       *conform.list_all_formatters*
    List information about all filetype-configured formatters


get_formatter_info({formatter}, {bufnr}): conform.FormatterInfo *conform.get_formatter_info*
    Get information about a formatter (including availability)

    Parameters:
      {formatter} `string` The name of the formatter
      {bufnr}     `nil|integer`

--------------------------------------------------------------------------------
FORMATTERS                                                    *conform-formatters*

`alejandra` - The Uncompromising Nix Code Formatter.
`autoflake` - Removes unused imports and unused variables as reported by
            pyflakes.
`autopep8` - A tool that automatically formats Python code to conform to the PEP
           8 style guide.
`beautysh` - A Bash beautifier for the masses.
`biome` - A toolchain for web projects, aimed to provide functionalities to
        maintain them.
`black` - The uncompromising Python code formatter.
`buf` - A new way of working with Protocol Buffers
`clang_format` - Tool to format C/C++/… code according to a set of rules and
               heuristics.
`cljstyle` - Formatter for Clojure code.
`cmake_format` - Parse cmake listfiles and format them nicely.
`codespell` - Check code for common misspellings.
`dart_format` - Replace the whitespace in your program with formatting that
              follows Dart guidelines.
`deno_fmt` - Use [Deno](https://deno.land/) to format TypeScript,
           JavaScript/JSON and markdown.
`dfmt` - Formatter for D source code.
`djlint` - ✨ HTML Template Linter and Formatter. Django - Jinja - Nunjucks -
         Handlebars - GoLang.
`elm_format` - elm-format formats Elm source code according to a standard set of
             rules based on the official [Elm Style Guide](https://elm-
             lang.org/docs/style-guide).
`erb_format` - Format ERB files with speed and precision.
`eslint_d` - Like ESLint, but faster.
`fish_indent` - Indent or otherwise prettify a piece of fish code.
`gdformat` - A formatter for Godot's gdscript.
`gofmt` - Formats go programs.
`gofumpt` - Enforce a stricter format than gofmt, while being backwards
          compatible. That is, gofumpt is happy with a subset of the formats
          that gofmt is happy with.
`goimports` - Updates your Go import lines, adding missing ones and removing
            unreferenced ones.
`golines` - A golang formatter that fixes long lines
`htmlbeautifier` - A normaliser/beautifier for HTML that also understands
                 embedded Ruby. Ideal for tidying up Rails templates.
`isort` - Python utility / library to sort imports alphabetically and
        automatically separate them into sections and by type.
`jq` - Command-line JSON processor.
`latexindent` - A perl script for formatting LaTeX files that is generally
              included in major TeX distributions.
`markdownlint` - A Node.js style checker and lint tool for Markdown/CommonMark
               files.
`nixfmt` - nixfmt is a formatter for Nix code, intended to apply a uniform
         style.
`nixpkgs_fmt` - nixpkgs-fmt is a Nix code formatter for nixpkgs.
`ocamlformat` - Auto-formatter for OCaml code.
`perlimports` - Make implicit Perl imports explicit
`perltidy` - Perl::Tidy, a source code formatter for Perl
`pg_format` - PostgreSQL SQL syntax beautifier.
`prettier` - Prettier is an opinionated code formatter. It enforces a consistent
           style by parsing your code and re-printing it with its own rules that
           take the maximum line length into account, wrapping code when
           necessary.
`prettierd` - prettier, as a daemon, for ludicrous formatting speed.
`rubocop` - Ruby static code analyzer and formatter, based on the community Ruby
          style guide.
`ruff` - An extremely fast Python linter, written in Rust.
`rustfmt` - A tool for formatting rust code according to style guidelines.
`scalafmt` - Code formatter for Scala.
`shellcheck` - A static analysis tool for shell scripts.
`shellharden` - The corrective bash syntax highlighter
`shfmt` - A shell parser, formatter, and interpreter with `bash` support.
`sql_formatter` - A whitespace formatter for different query languages.
`stylelint` - A mighty CSS linter that helps you avoid errors and enforce
            conventions.
`stylua` - An opinionated code formatter for Lua.
`swift_format` - Swift formatter from apple. Requires building from source with
               `swift build`.
`swiftformat` - SwiftFormat is a code library and command-line tool for
              reformatting `swift` code on macOS or Linux.
`taplo` - A TOML toolkit written in Rust
`terraform_fmt` - The terraform-fmt command rewrites `terraform` configuration
                files to a canonical format and style.
`trim_newlines` - Trim new lines with awk
`trim_whitespace` - Trim whitespaces with awk
`uncrustify` - A source code beautifier for C, C++, C#, ObjectiveC, D, Java,
             Pawn and Vala.
`xmlformat` - xmlformatter is an Open Source Python package, which provides
            formatting of XML documents.
`yamlfix` - A configurable YAML formatter that keeps comments.
`yamlfmt` - yamlfmt is an extensible command line tool or library to format yaml
          files.
`yapf` - Yet Another Python Formatter.
`zigfmt` - Reformat Zig source into canonical form.

--------------------------------------------------------------------------------
AUTOFORMAT                                                    *conform-autoformat*

If you want more complex logic than the `format_on_save` option allows, you can
write it yourself using your own autocmd. For example:
>lua
    -- if format_on_save is a function, it will be called during BufWritePre
    require("conform").setup({
      format_on_save = function(bufnr)
        -- Disable autoformat on certain filetypes
        local ignore_filetypes = { "sql", "java" }
        if vim.tbl_contains(ignore_filetypes, vim.bo[bufnr].filetype) then
          return
        end
        -- Disable with a global or buffer-local variable
        if vim.g.disable_autoformat or vim.b[bufnr].disable_autoformat then
          return
        end
        -- Disable autoformat for files in a certain path
        local bufname = vim.api.nvim_buf_get_name(bufnr)
        if bufname:match("/node_modules/") then
          return
        end
        -- ...additional logic...
        return { timeout_ms = 500, lsp_fallback = true }
      end,
    })

    -- There is a similar affordance for format_after_save, which uses BufWritePost.
    -- This is good for formatters that are too slow to run synchronously.
    require("conform").setup({
      format_after_save = function(bufnr)
        if vim.g.disable_autoformat or vim.b[bufnr].disable_autoformat then
          return
        end
        -- ...additional logic...
        return { lsp_fallback = true }
      end,
    })
<

================================================================================
vim:tw=80:ts=2:ft=help:norl:syntax=help: