Skip to content

Commit d1d182b

Browse files
abashevabashev
committed
Add the Get started section
One short page per way of running the formatter: the Gradle plugin, the command line, IntelliJ IDEA, Eclipse, and the GitHub Action with its pre-commit hook. Every command and build snippet on these pages was run against the published 2.98.0.1 artifacts. That run showed that formatDiff fails with an IllegalAccessError in a plain consumer build, so the Gradle page leads with the two settings that fix it, the native formatter property and the add-exports JVM flags, and the home page quick start now carries the property too. A multi-project build also needs Maven Central declared for the root project, because the formatter is resolved there. The IntelliJ page installs from the release zip, since the plugin is not on the Marketplace yet.
1 parent 300fb01 commit d1d182b

8 files changed

Lines changed: 441 additions & 4 deletions

File tree

‎docs/get-started/command-line.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# Command line
2+
3+
The formatter comes as a native binary that needs no Java, and as a runnable jar for every platform
4+
the binaries do not cover.
5+
6+
## Download
7+
8+
Pick the file for your platform from the
9+
[latest release](https://github.com/openjavaformat/open-java-format/releases/latest).
10+
11+
| Platform | File |
12+
| --- | --- |
13+
| Linux x86-64, glibc | `open-java-format-linux-glibc_x86-64` |
14+
| Linux AArch64, glibc | `open-java-format-linux-glibc_aarch64` |
15+
| macOS, Apple silicon | `open-java-format-macos_aarch64` |
16+
| macOS, Intel | `open-java-format-macos_x86-64` |
17+
| Anything else with Java 21 or later | `open-java-format-2.98.0.1-all.jar` |
18+
19+
There is no native binary for Windows or for musl-based Linux such as Alpine. Use the jar there.
20+
21+
``` sh title="Native binary, here for Apple silicon"
22+
curl -LO https://github.com/openjavaformat/open-java-format/releases/download/2.98.0.1/open-java-format-macos_aarch64
23+
chmod +x open-java-format-macos_aarch64
24+
./open-java-format-macos_aarch64 --version
25+
```
26+
27+
Rename the file to `open-java-format` and move it to a directory on your `PATH`. The examples below
28+
assume you did.
29+
30+
!!! note "macOS and files downloaded with a browser"
31+
32+
macOS refuses to run a binary that a browser downloaded. Clear the quarantine flag first with
33+
`xattr -d com.apple.quarantine open-java-format-macos_aarch64`. A file fetched with `curl` does
34+
not get the flag.
35+
36+
``` sh title="Runnable jar"
37+
curl -LO https://github.com/openjavaformat/open-java-format/releases/download/2.98.0.1/open-java-format-2.98.0.1-all.jar
38+
java -jar open-java-format-2.98.0.1-all.jar --version
39+
```
40+
41+
The jar carries its dependencies and the `Add-Exports` entries the formatter needs, so it runs
42+
without JVM flags.
43+
44+
## Verify the download
45+
46+
Every release has a `checksums_sha256.txt`. Download it next to your file and check:
47+
48+
=== "macOS"
49+
50+
``` sh
51+
shasum -a 256 --ignore-missing -c checksums_sha256.txt
52+
```
53+
54+
=== "Linux"
55+
56+
``` sh
57+
sha256sum --ignore-missing -c checksums_sha256.txt
58+
```
59+
60+
## Format and check
61+
62+
Pass `--ojf` every time. Without a style flag the formatter uses Google Java Style, and the old
63+
`--palantir` flag is no longer accepted.
64+
65+
``` sh title="Format files in place"
66+
open-java-format --ojf --replace src/main/java/com/example/Hello.java
67+
```
68+
69+
``` sh title="Format every tracked Java file"
70+
open-java-format --ojf --replace $(git ls-files '*.java')
71+
```
72+
73+
``` sh title="Check without changing anything"
74+
open-java-format --ojf --dry-run --set-exit-if-changed $(git ls-files '*.java')
75+
```
76+
77+
The check prints the files that would change and exits with 1 if there are any, which is what a CI
78+
step needs.
79+
80+
``` sh title="Format standard input"
81+
cat Hello.java | open-java-format --ojf -
82+
```
83+
84+
## Options
85+
86+
| Option | What it does |
87+
| --- | --- |
88+
| `--ojf` | Use the open-java-format style: 120 columns, 4-space indents |
89+
| `--replace`, `-i` | Write the result back to the files instead of printing it |
90+
| `--dry-run`, `-n` | Print the files that would change, change nothing |
91+
| `--set-exit-if-changed` | Exit with 1 if anything would change |
92+
| `-` | Format standard input to standard output |
93+
| `--lines 5:10` | Format only these lines, counted from 1 |
94+
| `--fix-imports-only` | Sort imports and remove unused ones, format nothing else |
95+
| `--skip-sorting-imports` | Leave the import order alone |
96+
| `--skip-removing-unused-imports` | Keep unused imports |
97+
| `--skip-reflowing-long-strings` | Do not rewrap string literals that pass the column limit |
98+
| `@file` | Read options and file names from a file |
99+
| `--version`, `--help` | Print the version, or every option |

‎docs/get-started/eclipse.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Eclipse
2+
3+
The plugin adds open-java-format as a formatter implementation for the Java editor. Eclipse has to
4+
run on Java 21 or later, as current Eclipse packages do.
5+
6+
## Install
7+
8+
1. Download `open-java-format-eclipse-plugin-2.98.0.1.jar` from the
9+
[latest release](https://github.com/openjavaformat/open-java-format/releases/latest).
10+
2. Open `eclipse.ini` and add these lines after `-vmargs`. The formatter reaches into javac, and
11+
these options allow it.
12+
13+
``` ini title="eclipse.ini"
14+
--add-exports=jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED
15+
--add-exports=jdk.compiler/com.sun.tools.javac.file=ALL-UNNAMED
16+
--add-exports=jdk.compiler/com.sun.tools.javac.parser=ALL-UNNAMED
17+
--add-exports=jdk.compiler/com.sun.tools.javac.tree=ALL-UNNAMED
18+
--add-exports=jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED
19+
```
20+
21+
3. Copy the jar into the `dropins` folder of your Eclipse installation.
22+
4. Start Eclipse once with `eclipse -clean`.
23+
24+
## Select the formatter
25+
26+
Open **Window → Preferences**, or **Eclipse → Settings** on macOS. Go to **Java → Code Style →
27+
Formatter** and pick **open-java-format** under **Formatter implementation**.
28+
29+
## If formatting fails
30+
31+
An `IllegalAccessError` in the workspace log means the options from `eclipse.ini` did not reach the
32+
JVM. Keep each option and its value on one line, joined by `=`. The Eclipse launcher starts the JVM
33+
inside its own process, and an option split over two lines does not take effect.

‎docs/get-started/github-actions.md‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
# GitHub Action and pre-commit
2+
3+
Both checks run the native binary, so they need no Java, Maven or Gradle. They work on Linux with
4+
glibc and on macOS. There is no native binary for Windows or for musl-based Linux such as Alpine.
5+
6+
## Check pull requests and pushes
7+
8+
``` yaml title=".github/workflows/format.yml"
9+
on:
10+
pull_request:
11+
push:
12+
branches: [main]
13+
14+
jobs:
15+
format:
16+
runs-on: ubuntu-latest
17+
steps:
18+
- uses: actions/checkout@v7
19+
20+
- uses: openjavaformat/open-java-format-action@v1
21+
with:
22+
version: '2.98.0.1'
23+
mode: ${{ github.event_name == 'push' && 'all' || 'changed' }}
24+
```
25+
26+
The [action](https://github.com/openjavaformat/open-java-format-action) downloads the binary, lists
27+
the files that are not formatted and fails the job if there are any.
28+
29+
| Input | Default | Meaning |
30+
| --- | --- | --- |
31+
| `version` | `2.98.0.1` | The formatter version to download |
32+
| `mode` | `changed` | `changed` checks the files of the pull request or push, `all` checks every `.java` file |
33+
34+
On a pull request `changed` takes the file list from the pull request itself. On a push it compares
35+
the commits before and after, which needs that history in the checkout: either use `mode: all` for
36+
pushes, as above, or check out with `fetch-depth: 0`.
37+
38+
## Fix what the check found
39+
40+
Run the formatter locally with the same version, then commit the result. See
41+
[Command line](command-line.md) for the download.
42+
43+
``` sh
44+
open-java-format --ojf --replace path/to/File.java
45+
```
46+
47+
## Exclude files
48+
49+
Both the action and the hook read an optional `.open-java-format-exclude` file in the repository
50+
root. Every line that is not empty and not a comment is a git pathspec, and a Java file that matches
51+
one is skipped.
52+
53+
``` gitignore title=".open-java-format-exclude"
54+
# Standalone jbang scripts: the formatter would rewrite their //DEPS directives
55+
samples/**
56+
57+
# Generated sources
58+
**/build/generated/**
59+
```
60+
61+
## Git pre-commit hook
62+
63+
The same check can stop a commit before it reaches CI. Copy the hook script from the action's
64+
repository into your project:
65+
66+
``` sh
67+
curl -fsSL https://raw.githubusercontent.com/openjavaformat/open-java-format-action/v1/pre-commit -o .git/hooks/pre-commit
68+
chmod +x .git/hooks/pre-commit
69+
```
70+
71+
On its first run the hook downloads the native binary and caches it in `~/.cache/open-java-format`.
72+
After that it checks only the staged `.java` files of each commit, and when one is not formatted it
73+
prints the command that fixes it.
74+
75+
To share the hook with the whole team, keep it in the repository instead:
76+
77+
``` sh
78+
mkdir -p .githooks
79+
curl -fsSL https://raw.githubusercontent.com/openjavaformat/open-java-format-action/v1/pre-commit -o .githooks/pre-commit
80+
chmod +x .githooks/pre-commit
81+
git config core.hooksPath .githooks
82+
```
83+
84+
The script pins its formatter version in `FORMATTER_VERSION` at the top. Keep it in step with the
85+
`version` your workflow passes to the action.

‎docs/get-started/gradle.md‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
# Gradle plugin
2+
3+
The plugin adds a task that formats the lines you changed, and it keeps IntelliJ IDEA on the same
4+
formatter version as the build. It needs Gradle 9 and a Gradle daemon running on Java 21 or later.
5+
6+
## Apply the plugin
7+
8+
=== "Groovy"
9+
10+
``` groovy title="build.gradle"
11+
plugins {
12+
id 'java'
13+
id 'dev.openjavaformat.java-format' version '2.98.0.1'
14+
}
15+
16+
repositories {
17+
mavenCentral()
18+
}
19+
```
20+
21+
=== "Kotlin"
22+
23+
``` kotlin title="build.gradle.kts"
24+
plugins {
25+
java
26+
id("dev.openjavaformat.java-format") version "2.98.0.1"
27+
}
28+
29+
repositories {
30+
mavenCentral()
31+
}
32+
```
33+
34+
The formatter itself is downloaded from Maven Central, in the same version as the plugin.
35+
36+
## Choose how the formatter runs
37+
38+
The formatter reads javac's internal classes, which a plain Gradle JVM does not open up. Without one
39+
of the two settings below, `formatDiff` fails with an `IllegalAccessError` that mentions
40+
`module jdk.compiler does not export com.sun.tools.javac.parser`.
41+
42+
=== "Native binary"
43+
44+
``` properties title="gradle.properties"
45+
openjavaformat.native.formatter=true
46+
```
47+
48+
Gradle then runs the formatter as a native binary, outside its own JVM. This works on Linux
49+
with glibc and on macOS.
50+
51+
=== "On the Gradle JVM"
52+
53+
``` properties title="gradle.properties"
54+
org.gradle.jvmargs=--add-exports jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED \
55+
--add-exports jdk.compiler/com.sun.tools.javac.file=ALL-UNNAMED \
56+
--add-exports jdk.compiler/com.sun.tools.javac.parser=ALL-UNNAMED \
57+
--add-exports jdk.compiler/com.sun.tools.javac.tree=ALL-UNNAMED \
58+
--add-exports jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED
59+
```
60+
61+
This works on every platform, Windows included. If the file already sets
62+
`org.gradle.jvmargs`, add the flags to that line instead of writing a second one.
63+
64+
## Format what you changed
65+
66+
``` sh
67+
./gradlew formatDiff
68+
```
69+
70+
The task looks at `git diff HEAD` and formats only the changed lines of the `.java` files in it.
71+
With a clean working tree it has nothing to do.
72+
73+
## Multi-project builds
74+
75+
Declare the plugin once in the root project and apply it wherever there is Java code. The formatter
76+
is resolved by the root project, so the root project needs the repository too.
77+
78+
=== "Groovy"
79+
80+
``` groovy title="build.gradle"
81+
plugins {
82+
id 'dev.openjavaformat.java-format' version '2.98.0.1' apply false
83+
}
84+
85+
allprojects {
86+
repositories {
87+
mavenCentral()
88+
}
89+
}
90+
91+
subprojects {
92+
apply plugin: 'java'
93+
apply plugin: 'dev.openjavaformat.java-format'
94+
}
95+
```
96+
97+
=== "Kotlin"
98+
99+
``` kotlin title="build.gradle.kts"
100+
plugins {
101+
id("dev.openjavaformat.java-format") version "2.98.0.1" apply false
102+
}
103+
104+
allprojects {
105+
repositories {
106+
mavenCentral()
107+
}
108+
}
109+
110+
subprojects {
111+
apply(plugin = "java")
112+
apply(plugin = "dev.openjavaformat.java-format")
113+
}
114+
```
115+
116+
## IntelliJ IDEA
117+
118+
When the project is opened in IntelliJ IDEA, the plugin writes the formatter settings into `.idea`,
119+
and the [IDE plugin](intellij-idea.md) then formats with the version the build uses. The IDE plugin
120+
is installed separately.

‎docs/get-started/index.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# Get started
2+
3+
open-java-format runs in the build, in the editor, on the command line and in CI. Every route uses
4+
the same formatter, so they all produce the same files. Set up the ones your project needs.
5+
6+
!!! info "Requirements"
7+
8+
The current version is **2.98.0.1**. Everything except the native binaries needs Java 21 or
9+
later, and the Gradle plugin needs Gradle 9.
10+
11+
<div class="grid cards" markdown>
12+
13+
- :simple-gradle:{ .lg .middle } __[Gradle plugin](gradle.md)__
14+
15+
---
16+
17+
Formats the lines you changed with `formatDiff` and keeps IntelliJ IDEA on the same formatter
18+
version as the build.
19+
20+
- :lucide-terminal:{ .lg .middle } __[Command line](command-line.md)__
21+
22+
---
23+
24+
A native binary for Linux and macOS, or a runnable jar anywhere else. Formats files in place or
25+
checks them.
26+
27+
- :simple-intellijidea:{ .lg .middle } __[IntelliJ IDEA](intellij-idea.md)__
28+
29+
---
30+
31+
Makes Reformat Code run open-java-format instead of the IDE's own Java formatter.
32+
33+
- :simple-eclipseide:{ .lg .middle } __[Eclipse](eclipse.md)__
34+
35+
---
36+
37+
Adds open-java-format as a formatter implementation for the Java editor.
38+
39+
- :simple-githubactions:{ .lg .middle } __[GitHub Action and pre-commit](github-actions.md)__
40+
41+
---
42+
43+
Fails a pull request, or stops a commit, when a Java file is not formatted.
44+
45+
</div>

0 commit comments

Comments
 (0)