cljfmt Documentation

cljfmt uses three types of indentation rules:

Default

Used when no other rule applies. For lists:

• If there is one or fewer elements on the first line, it indents by one space.
• If there are more than one element on the first line, it indents to the level of the second element.

Inner

Always indents by exactly two spaces on every line after the first, regardless of how many elements are on the first line.

Block

A hybrid approach. It follows Default rules up to a specific index. If the argument at that index is the first element in a line, it switches to Inner indentation.

Example of Block behavior with do [[:block 0]]:

• (do (println "A") (println "B")) -> Uses Default (indents to second element).
• (do\n (println "A")\n (println "B")) -> Uses Inner (constant 2-space indent because argument 0 starts the line).

When :align-map-columns? is true, :max-column-alignment-gap prevents excessive horizontal padding. If alignment would require more spaces than this limit (due to a long key), that specific row falls back to a single space. Shorter keys remain aligned normally.

;; 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

cljfmt uses two primary dimensions to determine indentation:

1. Index: The argument index in a list, starting from 0. In (foo bar baz), bar is index 0 and baz is index 1.
2. Depth: How deeply an element is nested relative to a parent. Elements in the parent list have depth 0, their children have depth 1, and so on.

Indentation rules are applied based on the depth of the first element in a line and the specific argument index being formatted.

In versions 0.11.x and later, the --indents and --alias-map CLI flags were removed in favor of configuration files.

The :indents key now replaces all default indents. To append to default indents instead of replacing them, use the :extra-indents key.

Backward Compatibility: If you need to maintain compatibility with older versions where :indents behaved like an append, use the :legacy/merge-indents? key:

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

This is equivalent to using :extra-indents.

To use cljfmt in a Leiningen project, add the plugin to your project.clj file:

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

Then run the following commands:

• Check for errors: lein cljfmt check
• Fix errors: lein cljfmt fix

Configuration can be added via a :cljfmt key in your project file.

You can install cljfmt as a standalone binary for quick access.

Linux or MacOS: 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)"

Homebrew (Recommended for MacOS): Use the weavejester/brew tap for better performance than the Homebrew core package:

brew install weavejester/brew/cljfmt

Windows: Download and extract the zipped binary manually from the releases page.

To install cljfmt as a Clojure CLI tool, run:

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

Once installed, use it with the -Tcljfmt flag:

• Check for errors: clj -Tcljfmt check
• Fix errors: clj -Tcljfmt fix

You can define cljfmt as a task in your bb.edn file to check formatting:

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

cljfmt is supported by several Clojure editing environments:

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

cljfmt allows you to customize indentation for specific functions or macros.

• Use :extra-indents to add new rules to the existing defaults.
• Use :indents to replace all default indentation rules with your own.

Keys in these maps can be:

• A symbol (unqualified matches all namespaces; qualified matches a specific namespace).
• A regular expression (use #re in EDN configuration files).
• A vector of two elements: [namespace-matcher name-matcher]. Both elements can be symbols or regular expressions.

To handle namespace resolution for unqualified symbols, you can provide an :alias-map or a :refer-map.

By default, cljfmt searches for configuration files in the current and parent directories. It looks for:

• .cljfmt.edn
• cljfmt.edn

The configuration file must contain a map of options. Since version 0.16.0, only .edn files are loaded by default for security reasons.