feat: formatter config can specify base formatter to extend (#800)

Author: stevearc

README.md

@@ -492,6 +492,15 @@ require("conform").formatters.shfmt = {
 }
 ```
 
+You can also specify which formatter to inherit from. This can be useful if you want to define multiple variants of a single formatter with slightly different options.
+
+```lua
+require("conform").formatters.deno_fmt_markdown = {
+  inherit = "deno_fmt",
+  append_args = { "--indent-width", "4" },
+}
+```
+
 ### Magic strings
 
 The following magic strings are available in `args` and `range_args`. They will be dynamically replaced at runtime with the relevant value.
@@ -623,7 +632,8 @@ require("conform").setup({
       env = {
         VAR = "value",
       },
-      -- Set to false to disable merging the config with the base definition
+      -- Set to false to disable merging the config with the base definition.
+      -- Can also be set to the name of the formatter to merge with (e.g. inherit = "black")
       inherit = true,
       -- When inherit = true, add these additional arguments to the beginning of the command.
       -- This can also be a function, like args
@@ -734,7 +744,7 @@ conform.format({ lsp_format = "fallback" })
 -- Asynchronously format the current buffer; will not block the UI
 conform.format({ async = true }, function(err, did_edit)
   -- called after formatting
-end
+end)
 -- Format the current buffer with a specific formatter
 conform.format({ formatters = { "ruff_fix" } })
 ```

doc/conform.txt

@@ -91,7 +91,8 @@ OPTIONS                                                          *conform-option
           env = {
             VAR = "value",
           },
-          -- Set to false to disable merging the config with the base definition
+          -- Set to false to disable merging the config with the base definition.
+          -- Can also be set to the name of the formatter to merge with (e.g. inherit = "black")
           inherit = true,
           -- When inherit = true, add these additional arguments to the beginning of the command.
           -- This can also be a function, like args
@@ -227,7 +228,7 @@ format({opts}, {callback}): boolean                               *conform.forma
       -- Asynchronously format the current buffer; will not block the UI
       conform.format({ async = true }, function(err, did_edit)
         -- called after formatting
-      end
+      end)
       -- Format the current buffer with a specific formatter
       conform.format({ formatters = { "ruff_fix" } })
 <

lua/conform/init.lua

@@ -402,7 +402,7 @@ local has_notified_ft_no_formatters = {}
 --- -- Asynchronously format the current buffer; will not block the UI
 --- conform.format({ async = true }, function(err, did_edit)
 ---   -- called after formatting
---- end
+--- end)
 --- -- Format the current buffer with a specific formatter
 --- conform.format({ formatters = { "ruff_fix" } })
 M.format = function(opts, callback)
@@ -700,6 +700,7 @@ end
 ---@param formatter string
 ---@param bufnr? integer
 ---@return nil|conform.FormatterConfig
+---@return nil|string error_msg
 M.get_formatter_config = function(formatter, bufnr)
   if not bufnr or bufnr == 0 then
     bufnr = vim.api.nvim_get_current_buf()
@@ -710,32 +711,41 @@ M.get_formatter_config = function(formatter, bufnr)
     override = override(bufnr)
   end
   if override and override.command and override.format then
-    local msg =
-      string.format("Formatter '%s' cannot define both 'command' and 'format' function", formatter)
-    notify_once(msg, vim.log.levels.ERROR)
-    return nil
+    return nil, "Cannot define both 'command' and 'format' function"
   end
 
   ---@type nil|conform.FormatterConfig
-  local config = override
-  if not override or override.inherit ~= false then
-    local ok, mod_config = pcall(require, "conform.formatters." .. formatter)
+  local config
+  local inherit = (override or {}).inherit
+  if inherit == nil then
+    inherit = true
+  end
+  if inherit then
+    local parent_formatter_name = formatter
+    if type(inherit) == "string" then
+      parent_formatter_name = inherit
+    end
+    local ok, mod_config = pcall(require, "conform.formatters." .. parent_formatter_name)
     if ok then
       if override then
         config = require("conform.util").merge_formatter_configs(mod_config, override)
       else
         config = mod_config
       end
     elseif override then
-      if override.command or override.format then
+      if override.inherit then
+        -- We attempted to explicitly inherit, but the `require` failed
+        return nil,
+          string.format(
+            "Attempting to inherit from non-existent built-in formatter '%s'",
+            parent_formatter_name
+          )
+      elseif override.command or override.format then
+        -- No built-in formatter to inherit from, but this is a complete definition
         config = override
       else
-        local msg = string.format(
-          "Formatter '%s' missing built-in definition\nSet `command` to get rid of this error.",
-          formatter
-        )
-        notify_once(msg, vim.log.levels.ERROR)
-        return nil
+        -- No built-in formatter to inherit from, and this is missing a `command` or `format` function
+        return nil, "Missing built-in definition. Set `command` to get rid of this error."
       end
     else
       return nil
@@ -756,13 +766,14 @@ M.get_formatter_info = function(formatter, bufnr)
   if not bufnr or bufnr == 0 then
     bufnr = vim.api.nvim_get_current_buf()
   end
-  local config = M.get_formatter_config(formatter, bufnr)
+  local config, missing_config_err = M.get_formatter_config(formatter, bufnr)
   if not config then
     return {
       name = formatter,
       command = formatter,
       available = false,
-      available_msg = "Unknown formatter. Formatter config missing or incomplete",
+      available_msg = missing_config_err
+        or "Unknown formatter. Formatter config missing or incomplete",
       error = true,
     }
   end

lua/conform/types.lua

@@ -33,7 +33,7 @@
 ---@alias conform.FormatterConfig conform.JobFormatterConfig|conform.LuaFormatterConfig
 
 ---@class (exact) conform.FormatterConfigOverride : conform.JobFormatterConfig
----@field inherit? boolean
+---@field inherit? boolean|string False creates an entirely new formatter. True will merge the config with the formatter defined in conform. Use a string name (e.g. "prettier") to inherit from that conform formatter.
 ---@field command? string|fun(self: conform.FormatterConfig, ctx: conform.Context): string
 ---@field prepend_args? string|string[]|fun(self: conform.FormatterConfig, ctx: conform.Context): string|string[]
 ---@field append_args? string|string[]|fun(self: conform.FormatterConfig, ctx: conform.Context): string|string[]

scripts/options_doc.lua

@@ -78,7 +78,8 @@ require("conform").setup({
       env = {
         VAR = "value",
       },
-      -- Set to false to disable merging the config with the base definition
+      -- Set to false to disable merging the config with the base definition.
+      -- Can also be set to the name of the formatter to merge with (e.g. inherit = "black")
       inherit = true,
       -- When inherit = true, add these additional arguments to the beginning of the command.
       -- This can also be a function, like args