A boot task for automatically reformatting your source code, similar to golang's gofmt.
Beautiful machine-formatted source code saves you time, helps you find bugs,
and avoids quibbles with collaborators. gofmt
's success has shown that
auto-formatting works for many golang teams; boot-fmt hopes to bring the same benefits
to Clojure(Script).
Powered by zprint and clj-rewrite, boot-fmt aims to provide a friendly command-line interface.
With boot installed, you can use boot-fmt from any directory:
boot -d boot-fmt fmt -f src
Note that you do not need to use boot
as your build tool or even have a
build.boot
present in the current directory. As long as boot is installed in
your system, boot-fmt will work just fine even if your project is managed by
leiningen.
However, if you do use boot
as your build tool, you may add
boot-fmt's coordinates as a dependency to your
build.boot
, e.g.:
(set-env! :dependencies '[[boot-fmt/boot-fmt "X.Y.Z" :scope "test"]])
(require '[boot-fmt.core :refer [fmt]])
There are three ways to select files to reformat. First, you can reformat all clj(s) files in the current git repository:
boot fmt --git
If you want to reformat a project managed by boot
and have already set up a
build.boot
with :source-paths
or :resource-paths
, you can instruct
boot-fmt to use these as its search path:
boot fmt --source
Finally, you can manually specify one more or more files or directories to scan. Directories are searched recursively for clj(s) source files:
boot fmt --files src
By specifying --files
multiple times, you can add multiple files or
directories to the search path. The --git
, --source
and --files
can be
combined.
Like gofmt, boot-fmt defaults to printing reformatted file contents to standard
output. Generally boot-fmt can operate in four different modes: print, list,
diff and overwrite. You can specify the operation to perform using the --mode
parameter.
If your project is under source control (e.g. using git), a good option is to let boot-fmt overwrite files in the current repository:
boot fmt --git --mode overwrite --really
You can use git diff
or git add -p
to see what was changed and to manually
confirm (or revert) reformated sections.
Note that overwriting files is potentially dangerous, so boot-fmt requires you
to add the --really
flag to indicate that you know what you're doing.
To preview changes, diff mode can be useful. Instead of overwriting files, diff mode prints a git-style diff to standard output:
boot fmt --git --mode diff
See the next section for a full description of each mode of operation.
You can see the options available on the command line:
boot -d boot-fmt fmt --help
Here's the output:
Reformat Clojure(script) source files, like gofmt
Print reformatted source code to standard output. Parameters specified using
`-f` can be files or directories. Directories are scanned recursively for
Clojure(Script) source files.
Specify the operation using the --mode parameter:
--mode print (default)
Print reformatted code to standard output
--mode diff
When reformatted code is different from original, print diff to standard output.
--mode list
Where reformatted code is different from original, print filename standard output.
--mode overwrite
Overwrite files with reformatted code. As this is a potentially dangerous
operation, you need to specify the --really flag in addition to setting
the --mode parameter
Options:
-h, --help Print this help info.
-m, --mode MODE MODE sets mode of operation, i.e. print, list, diff or overwrite. Defaults to print.
-r, --really In overwrite mode, files are overwritten only if the --really flag is set as well
-f, --files VAL Conj VAL onto the list of files or directories to format
-s, --source Automatically scan for files in boot source-paths and resource-paths
-g, --git Automatically scan for files in current git repository
-o, --options OPTS OPTS sets zprint options.
The output of zprint (and of boot-fmt) can be customized extensively.
For example, the default behavior is to indent the first argument of function calls with double-space indentation:
(org.springframework.context.support.ClassPathXmlApplicationContext.
- "supercalifragilisticexpialidocious")
+ "supercalifragilisticexpialidocious")
The Clojure
Community Style Guide and
Emacs's clojure-mode prefer single-space indentation in
such contexts
. If you prefer this community style over zprint's defaults, use the
--options {:style :community}
command line switch. See
this list
for other ways in which community style differs from the default style.
Using the --options
switch you can also fine-tune indentation rules,
including those for custom macros, by setting
zprint options, for example:
boot fmt -f src --options '{:style :community, :fn-map {":require" :force-nl-body, "ns" :arg1-body}}'
:source-paths
and :resource-paths
Copyright © 2016 Paulus Esterhazy
Distributed under the Eclipse Public License either version 1.0 or (at your option) any later version.