cljfmt

cljfmt is a tool for detecting and fixing formatting errors in Clojure code.

Its defaults are based on the Clojure Style Guide, but it also has many customization options to suit a particular project or team.

It is not the goal of the project to provide a one-to-one mapping between a Clojure syntax tree and formatted text; rather the intent is to correct formatting errors with minimal changes to the existing structure of the text.

If you want format completely unstructured Clojure code, the zprint project may be more suitable.

Breaking Changes in 0.11.x

The --indents and --alias-map keys have been removed from the CLI, in favor of using a configuration file instead.

The :indents key has been split into :indents and :extra-indents. The :indents key replaces all default indents, while the :extra-indents key will append to the default indents.

If you need to retain backward compatibility with an older version of cljfmt, then you can add the :legacy/merge-indents? key to your configuration:

{:legacy/merge-indents? true
 :indents {example.core/foo [[:inner 0]]}}

This will treat :indents as if it were :extra-indents. i.e. it is equivalent to:

{:extra-indents {example.core/foo [[:inner 0]]}}

Usage

cljfmt integrates with many existing build tools, or can be used as a library. As an end user, you have the choice of:

Standalone

The fastest way to run cljfmt is via a precompiled binary. If you're using Linux or MacOS, you can run the following command to install the binary into /usr/local/bin:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/weavejester/cljfmt/HEAD/install.sh)"

You can also run this command to update cljfmt to the latest version.

Alternatively, you can install cljfmt via Homebrew. If you do, it's highly recommended that you use the weavejester/brew tap. This will be much more performant than the Homebrew core cljfmt package.

brew install weavejester/brew/cljfmt

If you're using Windows, there's a zipped up binary you can download and extract manually.

To use cljfmt to check for formatting errors in your project, run:

cljfmt check

And to fix those errors:

cljfmt fix

Use --help for a list of all the command-line options.

For persistent configuration, you can use a configuration file.

Clojure Tools

The official Clojure CLI supports installation of thirdparty tools. To install cljfmt as a tool, run:

clj -Ttools install io.github.weavejester/cljfmt '{:git/tag "0.16.3"}' :as cljfmt

To use the tool to check for formatting errors in your project, run:

clj -Tcljfmt check

And to fix those errors:

clj -Tcljfmt fix

Leiningen

Leiningen is a popular Clojure build tool. To use cljfmt with Leiningen, add the following plugin to your project.clj file:

:plugins [[dev.weavejester/lein-cljfmt "0.16.3"]]

To use the plugin to check code for formatting errors, run:

lein cljfmt check

And to fix those errors:

lein cljfmt fix

To configure it, put a :cljfmt key and a map of options in your project file. See the configuration section for more details.

Library

cljfmt can be run as a library that formats a string of Clojure code or recursively checks / fixes paths like the CLI tool. First, add the dependency:

{:deps {dev.weavejester/cljfmt {:mvn/version "0.16.3"}}}

Then use the library:

Checking strings of code:

(require '[cljfmt.core :as fmt])

(fmt/reformat-string "(defn sum [x y]\n(+ x y))")
;; => "(defn sum [x y]\n  (+ x y))"

To load the configuration for the current directory:

(require '[cljfmt.config :as cfg])

(fmt/reformat-string "(+ x\ny)" (cfg/load-config))
;; => "(+ x\n   y)"

Checking / fixing paths recursively

Be sure to set the report fn to the clojure one as shown below. Otherwise the check and fix fns will assume they're running in console mode and will call System/exit, print to stdout, etc.

(require '[cljfmt.tool :as fmt]
         '[cljfmt.report :as report])

(fmt/check {:paths ["/path/to/check"], :report report/clojure})

Or to recursively fix paths:

(require '[cljfmt.tool :as fmt]
         '[cljfmt.report :as report])

(fmt/fix {:paths ["/path/to/fix"], :report report/clojure})

Babashka

cljfmt can also be used from Babashka, either as a library or as a tool that you define in your bb.edn file like so:

{:deps  {dev.weavejester/cljfmt {:mvn/version "0.16.3"}}
 :tasks {fmt {:doc "Check formatting with cljfmt"
              :requires ([cljfmt.tool :as fmt])
              :task (fmt/check {})}}}

Editor Integration

You can also use cljfmt via your editor. Several Clojure editing environments have support for cljfmt baked in:

• Calva (Visual Studio Code)
• CIDER (Emacs)
• clojureVSCode (Visual Studio Code)
• vim-cljfmt (Vim)

Configuration

In most environments, cljfmt will look for the following configuration files in the current and parent directories:

• .cljfmt.edn
• cljfmt.edn

The configuration file should contain a map of options.

Since 0.16.0, only .edn configuration files are loaded by default. You can enable reading of .clj configuration files with the --read-clj-config-files flag:

• .cljfmt.clj
• cljfmt.clj

If a .clj configuration file is detected without this flag, a warning is printed.

Leiningen

In Leiningen, the configuration is found in on the :cljfmt key in the project map:

:cljfmt {}

In order to load the standard configuration file from Leiningen, add the :load-config-file? key to the :cljfmt map:

:cljfmt {:load-config-file? true}

Formatting Options

• :alias-map - a map of namespace alias to fully qualified namespace names. May be symbols or strings. This option is unnecessary in most cases, because cljfmt will parse the ns declaration in each file. See [INDENTS.md][].

• :refer-map - a map of referred symbol names to fully qualified namespace names. May be symbols or strings. This option is unnecessary in most cases, because cljfmt will parse the ns declaration in each file to extract :refer mappings. Used for indentation rules when unqualified symbols need to be matched against qualified indent rules. See [INDENTS.md][].

• :aligned-forms - a map of symbols to indexes that tell cljfmt where to expect forms it should align. For example, {let #{0}} indicates that the first argument of let (the binding vector) should be aligned. This option will replace the default aligned forms. Used by :align-form-columns?. Experimental.

• :align-form-columns? - true if cljfmt should align the symbols and values within certain forms (such as let) so that they line up in columns. The forms are defined via the :aligned-forms and :extra-aligned-forms options. Defaults to false. Experimental.

• :align-map-columns? - true if cljfmt should align the keys and values of maps such that they line up in columns. Defaults to false. Experimental.

• :align-single-column-lines? - true if cljfmt should include lines with single columns (where the value is on the next line) when calculating column alignment. When false, forms with wrapped values won't cause excessive horizontal padding in other lines. Only applies when :align-form-columns? or :align-map-columns? is true. Defaults to false. Experimental.

• :max-column-alignment-gap - a positive integer that sets the maximum number of spaces allowed between a key and its aligned value. When alignment would produce more spaces than this limit on a given row (e.g. due to a long destructuring key), that row falls back to a single space instead. Rows with shorter keys are still aligned normally. Useful for preventing :align-map-columns? from producing excessive horizontal padding in maps that contain outlier keys such as destructuring forms. Defaults to nil (no limit). Experimental.

  ;; Input:
  {{:keys [several things here]} :sub-map
   {:keys [several things]}      :sub-map2
   :keys                         [direct values]
   :as                           everything}
  
  ;; With :align-map-columns? true and :max-column-alignment-gap 10:
  {{:keys [several things here]} :sub-map   ;; 1 space, aligned
   {:keys [several things]}      :sub-map2  ;; 6 spaces, still aligned (6 ≤ 10)
   :keys [direct values]                    ;; 25 spaces, falls back to 1 space
   :as everything}                          ;; 27 spaces, falls back to 1 space
  

• blank-lines-separate-alignment - true if cljfmt should treat blank lines as separators when aligning columns. When enabled, alignment groups are separated by blank lines, allowing independent alignment wi