danchr / sg-java-format

Reformats Java source code to comply with SG Java style; fork of google-java-format

sg-java-format

sg-java-format reformats Java source code to comply with the named style. We forked google-java-format 1.6 and modified it to support custom styles to enforce the Salling Group Java style.

Table of Contents

• 1. Using the formatter
  • 1.1. In CI
• 2. Motivation

To simplify integrating upstream changes, customizations in sg-java-format are kept to a minimum. A clear example of this is that sg-java-format itself is formatted using the Google style.

For more information about google-java-format, see the original project README.

1. Using the formatter

The easiest way to use the formatter is to commit the scripts/javafmtw wrapper and its configuration—​generated on its first execution—​to your repository, at a location of your preference, and execute that. In that instance you will likely want to ignore the Jar file.

Alternatively you can download the formatter and run it with:

java -jar /path/to/sg-java-format-1-all-deps.jar [options] [files...]

While you don’t have to do anything else to use sg-java-format, to actually take advantage of it you have to pass the --style option with one of its supported values, e.g. --style=salling-group.

ℹ️	sg-java-format aims to be a drop-in replacement for the version of google-java-format it was forked from.

🔥	The only supported use of sg-java-format is as a self-contained JAR file invoked headlessly. google-java-format offers additional integrations; these are not supported.

1.1. In CI

In CI, use sg-java-format as above but include these two options:

--set-exit-if-changed

Exit with non-zero status code if any of the named files would be reformatted.

--dry-run

Print the paths to files that would be reformatted but don’t reformat them. Optional, but helpful for troubleshooting.

🔥

sg-java-format cannot recurse through subtrees. For small sets of files you can leverage shopt -s globstar to name all Java files with **/*.java. With very large sets of files this will exceed the command line limit and you will need to process files in batches. When processing individual batches you have to make a decision about how the options above should combine to determine failure in your execution environment, in particular whether it should fail immediately or only after processing all files.

2. Motivation

Reasons for establishing a style guide and enforcing it with tooling are well understood and documented throughout the Internet and will not be reproduced here.

sg-java-format is based on google-java-format because that is a very well made application that solves the automatic formatting problem in a solid manner. google-java-format is non-configurable by design, which is highly advantageous in reducing human errors and misunderstandings and minimizing application complexity. These are desirable qualities for sg-java-format. Unfortunately Google’s own Java style is radically different from most other style variants in a few key ways that make it difficult to adopt. These qualities are not desirable for sg-java-format, which is why we forked the project. There are many other tools that purport to solve this problem, most of them with built-in configurability, but they tend to disappoint in various other ways like being egregiously non-idempotent or taking excessively long time to run.

It is not sg-java-format's goal to be “a configurable google-java-format”.