Merge pull request #603 from diffplug/feat/ratchetfrom-maven

Add `ratchetFrom` to maven

Author: nedtwigg

plugin-gradle/src/main/java/com/diffplug/gradle/spotless/GitRatchet.java renamed to lib-extra/src/main/java/com/diffplug/spotless/extra/GitRatchet.java

@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package com.diffplug.gradle.spotless;
+package com.diffplug.spotless.extra;
 
 import java.io.File;
 import java.io.IOException;
@@ -40,14 +40,20 @@
 import org.eclipse.jgit.treewalk.filter.IndexDiffFilter;
 import org.eclipse.jgit.treewalk.filter.PathFilter;
 import org.eclipse.jgit.util.FS;
-import org.gradle.api.Project;
 
 import com.diffplug.common.base.Errors;
 import com.diffplug.common.collect.HashBasedTable;
 import com.diffplug.common.collect.Table;
 import com.diffplug.spotless.FileSignature;
 
-class GitRatchet implements AutoCloseable {
+/**
+ * How to use:
+ * - For best performance, you should have one instance of GitRatchet, shared by all projects.
+ * - Use {@link #rootTreeShaOf(Object, String)} to turn `origin/master` into the SHA of the tree object at that reference
+ * - Use {@link #isClean(Object, ObjectId, File)} to see if the given file is "git clean" relative to that tree
+ * - If you have up-to-date checking and want the best possible performance, use {@link #subtreeShaOf(Object, ObjectId)} to optimize up-to-date checks on a per-project basis.
+ */
+public abstract class GitRatchet<Project> implements AutoCloseable {
 	/**
 	 * This is the highest-level method, which all the others serve.  Given the sha
 	 * of a git tree (not a commit!), and the file in question, this method returns
@@ -130,17 +136,17 @@ private static boolean worktreeIsCleanCheckout(TreeWalk treeWalk) {
 	private Repository repositoryFor(Project project) throws IOException {
 		Repository repo = gitRoots.get(project);
 		if (repo == null) {
-			if (isGitRoot(project.getProjectDir())) {
-				repo = createRepo(project.getProjectDir());
+			if (isGitRoot(getDir(project))) {
+				repo = createRepo(getDir(project));
 			} else {
-				Project parentProj = project.getParent();
+				Project parentProj = getParent(project);
 				if (parentProj == null) {
-					repo = traverseParentsUntil(project.getProjectDir().getParentFile(), null);
+					repo = traverseParentsUntil(getDir(project).getParentFile(), null);
 					if (repo == null) {
 						throw new IllegalArgumentException("Cannot find git repository in any parent directory");
 					}
 				} else {
-					repo = traverseParentsUntil(project.getProjectDir().getParentFile(), parentProj.getProjectDir());
+					repo = traverseParentsUntil(getDir(project).getParentFile(), getDir(parentProj));
 					if (repo == null) {
 						repo = repositoryFor(parentProj);
 					}
@@ -151,6 +157,10 @@ private Repository repositoryFor(Project project) throws IOException {
 		return repo;
 	}
 
+	protected abstract File getDir(Project project);
+
+	protected abstract @Nullable Project getParent(Project project);
+
 	private static @Nullable Repository traverseParentsUntil(File startWith, File file) throws IOException {
 		while (startWith != null) {
 			if (isGitRoot(startWith)) {
@@ -196,7 +206,7 @@ public synchronized ObjectId rootTreeShaOf(Project project, String reference) {
 				rootTreeShaCache.put(repo, reference, treeSha);
 			}
 			return treeSha;
-		} catch (Exception e) {
+		} catch (IOException e) {
 			throw Errors.asRuntime(e);
 		}
 	}
@@ -210,7 +220,7 @@ public synchronized ObjectId subtreeShaOf(Project project, ObjectId rootTreeSha)
 			ObjectId subtreeSha = subtreeShaCache.get(project);
 			if (subtreeSha == null) {
 				Repository repo = repositoryFor(project);
-				File directory = project.getProjectDir();
+				File directory = getDir(project);
 				if (repo.getWorkTree().equals(directory)) {
 					subtreeSha = rootTreeSha;
 				} else {
@@ -221,7 +231,7 @@ public synchronized ObjectId subtreeShaOf(Project project, ObjectId rootTreeSha)
 				subtreeShaCache.put(project, subtreeSha);
 			}
 			return subtreeSha;
-		} catch (Exception e) {
+		} catch (IOException e) {
 			throw Errors.asRuntime(e);
 		}
 	}

plugin-gradle/src/main/java/com/diffplug/gradle/spotless/GitRatchetGradle.java

@@ -0,0 +1,37 @@
+/*
+ * Copyright 2020 DiffPlug
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.diffplug.gradle.spotless;
+
+import java.io.File;
+
+import javax.annotation.Nullable;
+
+import org.gradle.api.Project;
+
+import com.diffplug.spotless.extra.GitRatchet;
+
+/** Gradle implementation of GitRatchet. */
+final class GitRatchetGradle extends GitRatchet<Project> {
+	@Override
+	protected File getDir(Project project) {
+		return project.getProjectDir();
+	}
+
+	@Override
+	protected @Nullable Project getParent(Project project) {
+		return project.getParent();
+	}
+}

plugin-gradle/src/main/java/com/diffplug/gradle/spotless/RegisterDependenciesTask.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 DiffPlug
+ * Copyright 2016-2020 DiffPlug
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -106,10 +106,10 @@ public void trivialFunction() throws IOException {
 		Files.write(Integer.toString(getSteps().size()), unitOutput, StandardCharsets.UTF_8);
 	}
 
-	GitRatchet gitRatchet = new GitRatchet();
+	GitRatchetGradle gitRatchet = new GitRatchetGradle();
 
 	@Internal
-	GitRatchet getGitRatchet() {
+	GitRatchetGradle getGitRatchet() {
 		return gitRatchet;
 	}
 }

plugin-gradle/src/main/java/com/diffplug/gradle/spotless/SpotlessTaskBase.java

@@ -76,7 +76,7 @@ public void setLineEndingsPolicy(LineEnding.Policy lineEndingsPolicy) {
 
 	/*** API which performs git up-to-date tasks. */
 	@Nullable
-	GitRatchet ratchet;
+	GitRatchetGradle ratchet;
 	/** The sha of the tree at repository root, used for determining if an individual *file* is clean according to git. */
 	ObjectId rootTreeSha;
 	/**
@@ -86,14 +86,14 @@ public void setLineEndingsPolicy(LineEnding.Policy lineEndingsPolicy) {
 	 */
 	private ObjectId subtreeSha = ObjectId.zeroId();
 
-	public void setupRatchet(GitRatchet gitRatchet, String ratchetFrom) {
+	public void setupRatchet(GitRatchetGradle gitRatchet, String ratchetFrom) {
 		ratchet = gitRatchet;
 		rootTreeSha = gitRatchet.rootTreeShaOf(getProject(), ratchetFrom);
 		subtreeSha = gitRatchet.subtreeShaOf(getProject(), rootTreeSha);
 	}
 
 	@Internal
-	GitRatchet getRatchet() {
+	GitRatchetGradle getRatchet() {
 		return ratchet;
 	}
 

plugin-gradle/src/test/java/com/diffplug/gradle/spotless/RatchetFromTest.java renamed to plugin-gradle/src/test/java/com/diffplug/gradle/spotless/GitRatchetGradleTest.java

@@ -34,7 +34,7 @@
 import org.gradle.testkit.runner.TaskOutcome;
 import org.junit.Test;
 
-public class RatchetFromTest extends GradleIntegrationHarness {
+public class GitRatchetGradleTest extends GradleIntegrationHarness {
 	private static final String TEST_PATH = "src/markdown/test.md";
 
 	private Git initRepo() throws IllegalStateException, GitAPIException, IOException {

plugin-maven/CHANGES.md

@@ -4,8 +4,9 @@ We adhere to the [keepachangelog](https://keepachangelog.com/en/1.0.0/) format (
 
 ## [Unreleased]
 ### Added
-* `prettier` will now autodetect the parser (and formatter) to use based on the filename, unless you override this using `config` or `configFile` with the option `parser` or `filepath` ([#620](https://github.com/diffplug/spotless/pull/620)).
+* You can now ratchet a project's style by limiting Spotless only to files which have changed since a given [git reference](https://javadoc.io/static/org.eclipse.jgit/org.eclipse.jgit/5.6.1.202002131546-r/org/eclipse/jgit/lib/Repository.html#resolve-java.lang.String-), e.g. `ratchetFrom 'origin/main'`. ([#590](https://github.com/diffplug/spotless/pull/590))
 * Huge speed improvement for multi-module projects thanks to improved cross-project classloader caching ([#571](https://github.com/diffplug/spotless/pull/571), fixes [#559](https://github.com/diffplug/spotless/issues/559)).
+* `prettier` will now autodetect the parser (and formatter) to use based on the filename, unless you override this using `config` or `configFile` with the option `parser` or `filepath` ([#620](https://github.com/diffplug/spotless/pull/620)).
 
 ## [1.31.3] - 2020-06-17
 ### Changed

plugin-maven/README.md

@@ -594,7 +594,25 @@ By default, `spotless:check` is bound to the `verify` phase.  You might want to
 - If you don't like what spotless did, `git reset --hard`
 - If you'd like to remove the "checkpoint" commit, `git reset --soft head~1` will make the checkpoint commit "disappear" from history, but keeps the changes in your working directory.
 
-<a name="examples"></a>
+<a name="ratchet"></a>
+
+## How can I enforce formatting gradually?
+
+If your project is not currently enforcing formatting, then it can be a noisy transition.  Having a giant commit where every single file gets changed makes the history harder to read.  To address this, you can use the `ratchet` feature:
+
+```xml
+<configuration>
+  <ratchetFrom>origin/main</ratchetFrom> <!-- only format files which have changed since origin/main -->
+  <!-- ... define formats ... -->
+</configuration>
+```
+
+In this mode, Spotless will apply only to files which have changed since `origin/main`.  You can ratchet from [any point you want](https://javadoc.io/static/org.eclipse.jgit/org.eclipse.jgit/5.6.1.202002131546-r/org/eclipse/jgit/lib/Repository.html#resolve-java.lang.String-), even `HEAD`.  You can also set `ratchetFrom` per-format if you prefer (e.g. `<configuration><java><ratchetFrom>...`).
+
+However, we strongly recommend that you use a non-local branch, such as a tag or `origin/main`.  The problem with `HEAD` or any local branch is that as soon as you commit a file, that is now the canonical formatting, even if it was formatted incorrectly.  By instead specifying `origin/main` or a tag, your CI server will fail unless every changed file is at least as good or better than it was before the change.
+
+This is especially helpful for injecting accurate copyright dates using the [license step](#license-header).
+
 
 ## Can I apply Spotless to specific files?
 
@@ -606,6 +624,8 @@ cmd> mvn spotless:apply -DspotlessFiles=my/file/pattern.java,more/generic/.*-pat
 
 The patterns are matched using `String#matches(String)` against the absolute file path.
 
+<a name="examples"></a>
+
 ## Example configurations (from real-world projects)
 
 - [Apache Avro](https://github.com/apache/avro/blob/8026c8ffe4ef67ab419dba73910636bf2c1a691c/lang/java/pom.xml#L307-L334)

plugin-maven/build.gradle

@@ -78,6 +78,7 @@ dependencies {
 
 	implementation "com.diffplug.durian:durian-core:${VER_DURIAN}"
 	implementation "com.diffplug.durian:durian-collect:${VER_DURIAN}"
+	implementation "org.eclipse.jgit:org.eclipse.jgit:${VER_JGIT}"
 
 	testImplementation project(":testlib")
 	testImplementation "junit:junit:${VER_JUNIT}"

plugin-maven/src/main/java/com/diffplug/spotless/maven/AbstractSpotlessMojo.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 DiffPlug
+ * Copyright 2016-2020 DiffPlug
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -19,7 +19,13 @@
 
 import java.io.File;
 import java.io.IOException;
-import java.util.*;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Objects;
+import java.util.Optional;
+import java.util.Set;
 import java.util.function.Predicate;
 import java.util.regex.Pattern;
 import java.util.stream.Collectors;
@@ -36,6 +42,7 @@
 import org.eclipse.aether.RepositorySystemSession;
 import org.eclipse.aether.repository.RemoteRepository;
 
+import com.diffplug.common.collect.Iterables;
 import com.diffplug.spotless.Formatter;
 import com.diffplug.spotless.LineEnding;
 import com.diffplug.spotless.Provisioner;
@@ -76,6 +83,9 @@ public abstract class AbstractSpotlessMojo extends AbstractMojo {
 	@Parameter(defaultValue = DEFAULT_LINE_ENDINGS)
 	private LineEnding lineEndings;
 
+	@Parameter
+	private String ratchetFrom;
+
 	@Parameter
 	private LicenseHeader licenseHeader;
 
@@ -110,21 +120,28 @@ public abstract class AbstractSpotlessMojo extends AbstractMojo {
 	@Parameter(property = "spotlessFiles")
 	private String filePatterns;
 
-	protected abstract void process(List<File> files, Formatter formatter) throws MojoExecutionException;
+	protected abstract void process(Iterable<File> files, Formatter formatter) throws MojoExecutionException;
 
 	@Override
 	public final void execute() throws MojoExecutionException {
 		List<FormatterFactory> formatterFactories = getFormatterFactories();
-
 		for (FormatterFactory formatterFactory : formatterFactories) {
 			execute(formatterFactory);
 		}
 	}
 
 	private void execute(FormatterFactory formatterFactory) throws MojoExecutionException {
 		List<File> files = collectFiles(formatterFactory);
-		try (Formatter formatter = formatterFactory.newFormatter(files, getFormatterConfig())) {
-			process(files, formatter);
+		FormatterConfig config = getFormatterConfig();
+		Optional<String> ratchetFrom = formatterFactory.ratchetFrom(config);
+		Iterable<File> toFormat;
+		if (!ratchetFrom.isPresent()) {
+			toFormat = files;
+		} else {
+			toFormat = Iterables.filter(files, GitRatchetMaven.instance().isGitDirty(baseDir, ratchetFrom.get()));
+		}
+		try (Formatter formatter = formatterFactory.newFormatter(files, config)) {
+			process(toFormat, formatter);
 		}
 	}
 
@@ -172,7 +189,7 @@ private FormatterConfig getFormatterConfig() {
 		Provisioner provisioner = MavenProvisioner.create(resolver);
 		List<FormatterStepFactory> formatterStepFactories = getFormatterStepFactories();
 		FileLocator fileLocator = getFileLocator();
-		return new FormatterConfig(baseDir, encoding, lineEndings, provisioner, fileLocator, formatterStepFactories);
+		return new FormatterConfig(baseDir, encoding, lineEndings, Optional.ofNullable(ratchetFrom), provisioner, fileLocator, formatterStepFactories);
 	}
 
 	private FileLocator getFileLocator() {

plugin-maven/src/main/java/com/diffplug/spotless/maven/FormatterConfig.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 DiffPlug
+ * Copyright 2016-2020 DiffPlug
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -19,6 +19,7 @@
 
 import java.io.File;
 import java.util.List;
+import java.util.Optional;
 
 import com.diffplug.spotless.LineEnding;
 import com.diffplug.spotless.Provisioner;
@@ -27,14 +28,16 @@ public class FormatterConfig {
 
 	private final String encoding;
 	private final LineEnding lineEndings;
+	private final Optional<String> ratchetFrom;
 	private final Provisioner provisioner;
 	private final FileLocator fileLocator;
 	private final List<FormatterStepFactory> globalStepFactories;
 
-	public FormatterConfig(File baseDir, String encoding, LineEnding lineEndings, Provisioner provisioner,
+	public FormatterConfig(File baseDir, String encoding, LineEnding lineEndings, Optional<String> ratchetFrom, Provisioner provisioner,
 			FileLocator fileLocator, List<FormatterStepFactory> globalStepFactories) {
 		this.encoding = encoding;
 		this.lineEndings = lineEndings;
+		this.ratchetFrom = ratchetFrom;
 		this.provisioner = provisioner;
 		this.fileLocator = fileLocator;
 		this.globalStepFactories = globalStepFactories;
@@ -48,6 +51,10 @@ public LineEnding getLineEndings() {
 		return lineEndings;
 	}
 
+	public Optional<String> getRatchetFrom() {
+		return ratchetFrom;
+	}
+
 	public Provisioner getProvisioner() {
 		return provisioner;
 	}