// SPDX-License-Identifier: Apache-2.0 OR EUPL-1.2 = jfmt :toc: macro

jfmt is a standalone Java source code formatter — fast, consistent, and ready for CI.

image:https://github.com/bmarwell/jfmt/actions/workflows/build.yml/badge.svg["Build",link=https://github.com/bmarwell/jfmt/actions/workflows/build.yml] image:https://codecov.io/github/bmarwell/jfmt/graph/badge.svg?token=97T490QXQ2["codecov",link=https://codecov.io/github/bmarwell/jfmt] image:https://img.shields.io/badge/License-Apache_2.0-blue.svg["License",link=https://opensource.org/licenses/Apache-2.0] image:https://img.shields.io/badge/License-EUPL_1.2-blue["License EUPL",link=https://joinup.ec.europa.eu/software/page/eupl] image:https://img.shields.io/github/all-contributors/bmarwell/jfmt?color=ee8449&style=flat-square["All Contributors",link="#contributors"] image:https://deepwiki.com/badge.svg["Ask DeepWiki",link=https://deepwiki.com/bmarwell/jfmt]

toc::[]

== What is jfmt?

jfmt is an opinionated command-line Java formatter with a sane default configuration. It is built on top of the Eclipse JDT formatter engine — but unlike the Eclipse IDE, jfmt runs completely standalone as a native binary or JAR.

It’s designed for developers who want:

• predictable, idempotent formatting;
• a fast, zero-configuration CLI tool;
• an easy way to enforce consistent formatting locally and in CI.

In short: Run it locally before you commit. Let CI check it again. jfmt also normalizes all source files to UTF-8 encoding and Unix line endings (\n) to ensure consistent formatting across operating systems and editors. That’s all you need.

== Quick Start

. Install or build jfmt + You can run jfmt as a native binary or as a portable JAR (see <<Compiling>>).

. Format your code locally + [source,console]

Format and rewrite all Java files (write is the default command)

jfmt src/

or explicitly:

jfmt write src/

Or just check which files need formatting

jfmt list --all .

Show a diff of what would change

jfmt diff --all .

. Workflow Summary + |=== | Action | Who | Purpose | jfmt <files> + or jfmt write <files> | Developer | Format files locally before committing (write is the default) | jfmt diff | CI pipeline | Verify formatting consistency | jfmt print | Tooling | Print the correctly formatted output for the given file | jfmt list | Developer or CI | List unformatted files |===

== Why not Spotless or Checkstyle?

Spotless and Checkstyle are Maven or Gradle plugins that integrate deeply into build lifecycles. jfmt, on the other hand, is a self-contained command-line tool designed to be lightweight and fast — closer to gofmt or rustfmt.

|=== | Tool | Integration | Configuration | Typical Use | Spotless | Maven/Gradle plugin | Customizable | In build lifecycle | Checkstyle | Maven/Gradle plugin | Highly customizable | Style rule enforcement | jfmt | CLI tool / native binary | No config needed | Pre-commit & CI enforcement |===

jfmt complements these tools: you can use it alongside Checkstyle or in projects where build tooling is minimal.

== Goals

• 🚫​⚙️ No config file by default ** ship a sane default config, similar to https://github.com/palantir/palantir-java-format[palantir-java-format].
• 🪞 idempotent operation ** do not do other/additional changes upon subsequent reformat operations
• 📝 reading and writing ** allows output on stdout or overwriting the input files
• 🚯 no AST loss ** do not swallow comments, intentional empty lines and line breaks, etc.
• 🚀 FAST ** The project aims to create a GraalVM-based binary for most architectures, so it can operate almost as fast as gofmt or similar tools.
• 🧠 consistent import ordering ** automatically groups and sorts imports:
  1. all static imports first, followed by
  2. all other imports.

== Synopsis

[source]

Usage: jfmt [-hlV] [COMMAND] A command-line tool to format Java source code using JDT. -h, --help Show this help message and exit. -V, --version Print version information and exit. Commands: list Just list files which are not formatted correctly without printing a diff or writing changes. write, fix Write the formatted source code back to the file(s). This is the default command. print Print the correctly formatted output for the given file(s). Stops on the first file unless -a (--all) is given. In this case, the file name is printed before each output. diff Output in diff format. Normal diff is used unless -u is also given.

If no subcommand is specified, 'write' is used as the default.

=== list command

[source]

Usage: jfmt list [-ahV] [--no-color] [--config=<config>] [--config-file=<configFile>] [--import-order=<importOrder>] [--import-order-file=<importOrderFile>] <filesOrDirectories>... Just list files which are not formatted correctly without printing a diff or writing changes. <filesOrDirectories>... Files or directory to scan and to format. -a, --all Report all errors, not just the first one. --config=<config> Named config. Default: builtin. Available configs: builtin, equalsverifier --config-file=<configFile> Path to a config file. If unset (default), the named config (--config) will be used. -h, --help Show this help message and exit. --import-order=<importOrder> Named import order. Default: defaultorder. Available: defaultorder, equalsverifier, google, eclipse, intellij, enterprise --import-order-file=<importOrderFile> Path to an import-order properties file. If set, overrides --import-order. --no-color, --no-colour Force no colored output, even if the terminal supports it. -V, --version Print version information and exit.

=== write/fix command (default)

[source]

Usage: jfmt write [-ahV] [--no-color] [--config=<config>] [--config-file=<configFile>] [--import-order=<importOrder>] [--import-order-file=<importOrderFile>] <filesOrDirectories>... Write the formatted source code back to the file(s). This is the default command when no subcommand is specified. <filesOrDirectories>... Files or directory to scan and to format. -a, --all Report all errors, not just the first one. --config=<config> Named config. Default: builtin. Available configs: builtin, equalsverifier --config-file=<configFile> Path to a config file. If unset (default), the named config (--config) will be used. -h, --help Show this help message and exit. --import-order=<importOrder> Named import order. Default: defaultorder. Available: defaultorder, equalsverifier, google, eclipse, intellij, enterprise --import-order-file=<importOrderFile> Path to an import-order properties file. If set, overrides --import-order. --no-color, --no-colour Force no colored output, even if the terminal supports it. -V, --version Print version information and exit.

=== diff command

[source]

Usage: jfmt diff [-ahuV] [--no-color] [--config=<config>] [--config-file=<configFile>] [--context=<context>] [--import-order=<importOrder>] [--import-order-file=<importOrderFile>] <filesOrDirectories>... Output in diff format. Normal diff is used unless -u is also given. <filesOrDirectories>... Files or directory to scan and to format. -a, --all Report all errors, not just the first one. --config=<config> Named config. Default: builtin. Available configs: builtin, equalsverifier --config-file=<configFile> Path to a config file. If unset (default), the named config (--config) will be used. --context=<context> Number of context lines when in unified diff mode (-u). Defaults to 3. -h, --help Show this help message and exit. --import-order=<importOrder> Named import order. Default: defaultorder. Available: defaultorder, equalsverifier, google, eclipse, intellij, enterprise --import-order-file=<importOrderFile> Path to an import-order properties file. If set, overrides --import-order. --no-color, --no-colour Force no colored output, even if the terminal supports it. -u, --unified Output diff in unified format. Deactivated by default. -V, --version Print version information and exit.

== Implementation

• 💻 Uses PicoCLI for command line parsing
• 📝 Uses Eclipse JDT for formatting
• ⚙️ Uses GraalVM for creating native, statically linked stand-alone binaries
• 🌍 Automatically converts non-UTF-8 inputs to UTF-8 and replaces mixed or Windows line endings (\r\n) with Unix (\n) endings before formatting.
• 🧩 Sorts import statements according to a default two-group scheme + (+0=#+, +1=+ in Eclipse JDT syntax) — static imports first, then all others.

=== Roadmap

Features:

• [x] basic commands im