You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -623,77 +624,79 @@ However, we strongly recommend that you use a non-local branch, such as a tag or
623
624
624
625
This is especially helpful for injecting accurate copyright dates using the [license step](#license-header).
625
626
627
+
<a name="invisible"></a>
628
+
629
+
## Line endings and encodings (invisible stuff)
630
+
631
+
Spotless uses UTF-8 by default, but you can use [any encoding which Java supports](https://docs.oracle.com/javase/8/docs/technotes/guides/intl/encoding.doc.html). You can set it globally, and you can also set it per-format.
632
+
633
+
```gradle
634
+
spotless {
635
+
encoding 'UTF-8' // all formats will be interpreted as UTF-8
636
+
java {
637
+
encoding 'Cp1252' // except java, which will be Cp1252
638
+
```
639
+
640
+
Line endings can also be set globally or per-format using the `lineEndings` property. Spotless supports four line ending modes: `UNIX`, `WINDOWS`, `PLATFORM_NATIVE`, and `GIT_ATTRIBUTES`. The default value is `GIT_ATTRIBUTES`, and *we highly recommend that you* ***do not change*** *this value*. Git has opinions about line endings, and if Spotless and git disagree, then you're going to have a bad time.
641
+
642
+
You can easily set the line endings of different files using [a `.gitattributes` file](https://help.github.com/articles/dealing-with-line-endings/). Here's an example `.gitattributes` which sets all files to unix newlines: `* text eol=lf`.
643
+
626
644
<a name="custom"></a>
645
+
<a name="custom-rulwa"></a>
627
646
628
-
## Custom rules
647
+
## Custom steps
629
648
630
-
Spotless is a generic system for specifying a sequence of steps which are applied to a set of files.
649
+
As described in the [quickstart](#quickstart), Spotless is just a set of files ("target"), passed through a list of `String -> String` functions. The string each function gets will always have unix `\n` endings, and Spotless doesn't care which endings the function provides back, it will renormalize regardless. You can easily make a new step directly in your buildscript, like so:
631
650
632
651
```gradle
633
652
spotless {
634
-
// this will create two tasks: spotlessMiscCheck and spotlessMiscApply
635
653
format 'misc', {
636
-
// target determines which files this format will apply to
637
-
// - if you pass a string or a list of strings, they will be treated
638
-
// as 'include' parameters to a fileTree in the root directory
639
-
// - if you pass a FileCollection, it will pass through untouched
640
-
// e.g. project.files('build.gradle', 'settings.gradle')
641
-
// - if you pass anything else, it will be sent to project.files(yourArg)
// the files to be formatted = (target - targetExclude)
646
-
// NOTE: if target or targetExclude is called multiple times, only the
647
-
// last call is effective
648
-
649
-
// spotless has built-in rules for the most basic formatting tasks
650
-
trimTrailingWhitespace()
651
-
indentWithTabs() // or spaces. Takes an integer argument if you don't like 4
652
-
endWithNewline()
654
+
custom 'lowercase', { str -> str.toLowerCase() }
655
+
```
653
656
654
-
// you can also call out to your own function
655
-
custom 'superFormatter', {
656
-
// when writing a custom step, it will be helpful to know
657
-
// how the formatting process works, which is as follows:
657
+
However, custom rules will disable up-to-date checking and caching, unless you read [this javadoc](https://javadoc.io/static/com.diffplug.spotless/spotless-plugin-gradle/4.4.0/com/diffplug/gradle/spotless/FormatExtension.html#bumpThisNumberIfACustomStepChanges-int-) and follow its instructions carefully.
658
658
659
-
// 1) Load each target file, and convert it to unix-style line endings ('\n')
660
-
// 2) Pass its content through a series of steps, feeding the output of each step to the next
661
-
// 3) Put the correct line endings back on, then either check or apply
659
+
Another option is to create proper `FormatterStep` in your `buildSrc`, and then call [`addStep`](https://javadoc.io/static/com.diffplug.spotless/spotless-plugin-gradle/4.4.0/com/diffplug/gradle/spotless/FormatExtension.html#addStep-com.diffplug.spotless.FormatterStep-). The contributing guide describes [how to do this](https://github.com/diffplug/spotless/blob/main/CONTRIBUTING.md#how-to-add-a-new-formatterstep). If the step is generally-useful, we hope you'll open a PR to share it!
662
660
663
-
// each step receives a string as input, and should output
664
-
// a formatted string as output. Each step can trust that its
665
-
// input will have unix newlines, and it must promise to output
666
-
// only unix newlines. Other than that, anything is fair game!
667
-
}
668
-
}
669
-
}
661
+
662
+
```gradle
663
+
spotless {
664
+
format 'misc', {
665
+
addStep(MyFormatterStep.create())
670
666
```
671
667
672
-
If you use `custom` or `customLazy`, you might want to take a look at [this javadoc](https://javadoc.io/static/com.diffplug.spotless/spotless-plugin-gradle/4.4.0/com/diffplug/gradle/spotless/FormatExtension.html#bumpThisNumberIfACustomStepChanges-int-) for a big performance win.
668
+
### Throwing errors
673
669
674
-
See [`JavaExtension.java`](src/main/java/com/diffplug/gradle/spotless/JavaExtension.java) if you'd like to see how a language-specific set of custom rules is implemented. We'd love PR's which add support for other languages.
670
+
Ideally, your formatter will be able to silently fix any problems that it finds, that's the beauty of the `String -> String` model. But sometimes that's not possible. If you throw
675
671
676
-
If you'd like to create a one-off Spotless task outside of the `check`/`apply` framework, see [`FormatExtension.createIndependentApplyTask`](https://javadoc.io/static/com.diffplug.spotless/spotless-plugin-gradle/4.4.0/com/diffplug/gradle/spotless/FormatExtension.html#createIndependentApplyTask-java.lang.String-).
672
+
- `AssertionError` or a subclass -> Spotless reports as a problem in the file being formatted
673
+
- anything else -> Spotless reports as a bug in the formatter itself
677
674
678
-
<a name="invisible"></a>
675
+
## Multiple (or custom) language-specific blocks
679
676
680
-
## Line endings and encodings (invisible stuff)
677
+
The following two lines are exact synonyms:
681
678
682
-
Spotless uses UTF-8 by default, but you can use [any encoding which Java supports](https://docs.oracle.com/javase/8/docs/technotes/guides/intl/encoding.doc.html). You can set it globally, and you can also set it per-format.
679
+
```gradle
680
+
spotless { format 'java', com.diffplug.gradle.spotless.JavaExtension, { ... } }
681
+
spotless { java { ... } }
682
+
```
683
+
684
+
So if you want to have two different `java` blocks, you can do something like this:
683
685
684
686
```gradle
685
-
spotless {
686
-
java {
687
-
...
688
-
encoding 'Cp1252' // java will have Cp1252
689
-
}
690
-
encoding 'US-ASCII' // but all other formats will be interpreted as US-ASCII
691
-
}
687
+
spotless { java { ... } }
688
+
spotless { format 'javaFoo', com.diffplug.gradle.spotless.JavaExtension, { ... } }
689
+
// has to be 'javaFoo' not 'java' because each format needs a unique name
692
690
```
693
691
694
-
Line endings can also be set globally or per-format using the `lineEndings` property. Spotless supports four line ending modes: `UNIX`, `WINDOWS`, `PLATFORM_NATIVE`, and `GIT_ATTRIBUTES`. The default value is `GIT_ATTRIBUTES`, and *we highly recommend that you* ***do not change*** *this value*. Git has opinions about line endings, and if Spotless and git disagree, then you're going to have a bad time.
692
+
As a follow-on, you can make your own subclass to `FormatExtension` in the `buildSrc` directory, and then use it in your buildscript like so:
695
693
696
-
You can easily set the line endings of different files using [a `.gitattributes` file](https://help.github.com/articles/dealing-with-line-endings/). Here's an example `.gitattributes` which sets all files to unix newlines: `* text eol=lf`.
694
+
```gradle
695
+
spotless {
696
+
format 'foo', com.acme.FooLanguageExtension, {
697
+
```
698
+
699
+
If you'd like to create a one-off Spotless task outside of the `check`/`apply` framework, see [`FormatExtension.createIndependentApplyTask`](https://javadoc.io/static/com.diffplug.spotless/spotless-plugin-gradle/4.4.0/com/diffplug/gradle/spotless/FormatExtension.html#createIndependentApplyTask-java.lang.String-).
697
700
698
701
<a name="enforceCheck"></a>
699
702
@@ -719,13 +722,10 @@ You can fix (1) by excluding the file from formatting using the `targetExclude`
719
722
```gradle
720
723
spotless {
721
724
java {
722
-
googleJavaFormat()
723
-
custom 'my-glitchy-step', { }
725
+
custom 'my-glitchy-step', { ... }
724
726
725
727
ignoreErrorForStep('my-glitchy-step') // ignore errors on all files thrown by a specific step
726
728
ignoreErrorForPath('path/to/file.java') // ignore errors by all steps on this specific file
0 commit comments