[fix] Add git worktree support for ratchet functionality (#2779 fixes #2728)

Author: nedtwigg

CHANGES.md

@@ -10,16 +10,19 @@ This document is intended for Spotless developers.
 We adhere to the [keepachangelog](https://keepachangelog.com/en/1.0.0/) format (starting after version `1.27.0`).
 
 ## [Unreleased]
+
 ### Added
 - Add a `expandWildcardImports` API for java ([#2679](https://github.com/diffplug/spotless/issues/2594))
 - Add the ability to specify a wildcard version (`*`) for external formatter executables. ([#2757](https://github.com/diffplug/spotless/issues/2757))
 ### Fixed
 - Prevent race conditions when multiple npm-based formatters launch the server process simultaneously while sharing the same `node_modules` directory. ([#2786](https://github.com/diffplug/spotless/pull/2786))
+- Git ratchet no longer throws an error with Git worktrees. ([#2779](https://github.com/diffplug/spotless/issues/2779))
 ### Changes
 - Bump default `ktfmt` version to latest `0.59` -> `0.61`. ([2804](https://github.com/diffplug/spotless/pull/2804))
 - Bump default `ktlint` version to latest `1.7.1` -> `1.8.0`. ([2763](https://github.com/diffplug/spotless/pull/2763))
 - Bump default `gherkin-utils` version to latest `9.2.0` -> `10.0.0`. ([#2619](https://github.com/diffplug/spotless/pull/2619))
 
+
 ## [4.1.0] - 2025-11-18
 ### Changes
 - Bump default `ktfmt` version to latest `0.58` -> `0.59`. ([#2681](https://github.com/diffplug/spotless/pull/2681)
@@ -138,7 +141,7 @@ We adhere to the [keepachangelog](https://keepachangelog.com/en/1.0.0/) format (
 ### Changed
 * **BREAKING** Moved `PaddedCell.DirtyState` to its own top-level class with new methods. ([#2148](https://github.com/diffplug/spotless/pull/2148))
   * **BREAKING** Removed `isClean`, `applyTo`, and `applyToAndReturnResultIfDirty` from `Formatter` because users should instead use `DirtyState`.
-* `FenceStep` now uses `ConfigurationCacheHack`. ([#2378](https://github.com/diffplug/spotless/pull/2378) fixes [#2317](https://github.com/diffplug/spotless/issues/2317))  
+* `FenceStep` now uses `ConfigurationCacheHack`. ([#2378](https://github.com/diffplug/spotless/pull/2378) fixes [#2317](https://github.com/diffplug/spotless/issues/2317))
 ### Fixed
 * `ktlint` steps now read from the `string` instead of the `file` so they don't clobber earlier steps. (fixes [#1599](https://github.com/diffplug/spotless/issues/1599))
 
@@ -149,7 +152,7 @@ We adhere to the [keepachangelog](https://keepachangelog.com/en/1.0.0/) format (
 * `ConfigurationCacheHack` so we can support Gradle's configuration cache and remote build cache at the same time. ([#2298](https://github.com/diffplug/spotless/pull/2298) fixes [#2168](https://github.com/diffplug/spotless/issues/2168))
 ### Changed
 * Support configuring the Equo P2 cache. ([#2238](https://github.com/diffplug/spotless/pull/2238))
-* Add explicit support for JSONC / CSS via biome, via the file extensions `.css` and `.jsonc`. 
+* Add explicit support for JSONC / CSS via biome, via the file extensions `.css` and `.jsonc`.
   ([#2259](https://github.com/diffplug/spotless/pull/2259))
 * Bump default `buf` version to latest `1.24.0` -> `1.44.0`. ([#2291](https://github.com/diffplug/spotless/pull/2291))
 * Bump default `google-java-format` version to latest `1.23.0` -> `1.24.0`. ([#2294](https://github.com/diffplug/spotless/pull/2294))

lib-extra/src/main/java/com/diffplug/spotless/extra/GitRatchet.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2025 DiffPlug
+ * Copyright 2020-2026 DiffPlug
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -147,7 +147,7 @@ private static boolean worktreeIsCleanCheckout(TreeWalk treeWalk) {
 	 */
 	protected Repository repositoryFor(Project project) throws IOException {
 		File projectGitDir = GitWorkarounds.getDotGitDir(getDir(project));
-		if (projectGitDir == null || !RepositoryCache.FileKey.isGitRepository(projectGitDir, FS.DETECTED)) {
+		if (projectGitDir == null || !isGitRepository(projectGitDir)) {
 			throw new IllegalArgumentException("Cannot find git repository in any parent directory");
 		}
 		Repository repo = gitRoots.get(projectGitDir);
@@ -158,6 +158,28 @@ protected Repository repositoryFor(Project project) throws IOException {
 		return repo;
 	}
 
+	/**
+	 * Checks if the given directory is a valid git repository, including worktree repositories.
+	 * This is more lenient than {@link RepositoryCache.FileKey#isGitRepository} which doesn't
+	 * properly handle worktrees where some files are in the common directory.
+	 */
+	private static boolean isGitRepository(File gitDir) {
+		if (!gitDir.isDirectory()) {
+			return false;
+		}
+		// For worktrees, HEAD and commondir must exist (objects, refs, etc. are in commondir)
+		// For regular repos, HEAD and objects must exist
+		File headFile = new File(gitDir, Constants.HEAD);
+		File commonDirFile = new File(gitDir, "commondir");
+		if (commonDirFile.exists()) {
+			// This is a worktree - just check for HEAD and commondir
+			return headFile.exists();
+		} else {
+			// This is a regular repository - use standard check
+			return RepositoryCache.FileKey.isGitRepository(gitDir, FS.DETECTED);
+		}
+	}
+
 	protected abstract File getDir(Project project);
 
 	protected abstract @Nullable Project getParent(Project project);

plugin-maven/src/test/java/com/diffplug/spotless/maven/GitRatchetMavenTest.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020-2024 DiffPlug
+ * Copyright 2020-2026 DiffPlug
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -15,7 +15,9 @@
  */
 package com.diffplug.spotless.maven;
 
+import java.io.File;
 import java.io.IOException;
+import java.nio.file.Files;
 
 import org.eclipse.jgit.api.Git;
 import org.eclipse.jgit.api.errors.GitAPIException;
@@ -150,4 +152,81 @@ private void assertClean() throws Exception {
 	private void assertDirty() throws Exception {
 		mavenRunner().withArguments("spotless:check").runHasError();
 	}
+
+	@Test
+	void worktreeSupport() throws Exception {
+		// Set up main repository with explicit 'main' branch
+		// (Git.init() uses system default which may be 'master' on some systems)
+		Git mainGit = Git.init().setDirectory(rootFolder()).call();
+		RefDatabase refDB = mainGit.getRepository().getRefDatabase();
+		refDB.newUpdate(Constants.R_HEADS + "main", false).setNewObjectId(ObjectId.zeroId());
+		refDB.newUpdate(Constants.HEAD, false).link(Constants.R_HEADS + "main");
+		refDB.newUpdate(Constants.R_HEADS + Constants.MASTER, false).delete();
+
+		setFile(TEST_PATH).toContent("HELLO");
+		mainGit.add().addFilepattern(TEST_PATH).call();
+		mainGit.commit().setMessage("Initial commit").call();
+		mainGit.tag().setName("baseline").call();
+
+		// Set up a worktree manually (JGit doesn't support worktrees)
+		File worktreeDir = newFolder("worktree");
+		File mainGitDir = new File(rootFolder(), ".git");
+		File worktreeGitDir = new File(rootFolder(), ".git/worktrees/worktree");
+
+		// Create worktree structure
+		setFile(".git/worktrees/worktree/gitdir").toContent(worktreeDir.getAbsolutePath() + "/.git");
+		setFile(".git/worktrees/worktree/commondir").toContent("../..");
+		setFile(".git/worktrees/worktree/HEAD").toContent("ref: refs/heads/main");
+		setFile("worktree/.git").toContent("gitdir: " + worktreeGitDir.getAbsolutePath());
+
+		// Copy the test file to worktree (same as baseline so ratchet considers it clean)
+		setFile("worktree/" + TEST_PATH).toContent("HELLO");
+
+		// Copy Maven wrapper files to worktree
+		setFile("worktree/.gitattributes").toContent("* text eol=lf");
+		Files.copy(new File(rootFolder(), "mvnw").toPath(), new File(worktreeDir, "mvnw").toPath());
+		new File(worktreeDir, "mvnw").setExecutable(true);
+		Files.copy(new File(rootFolder(), "mvnw.cmd").toPath(), new File(worktreeDir, "mvnw.cmd").toPath());
+		new File(worktreeDir, ".mvn/wrapper").mkdirs();
+		Files.copy(new File(rootFolder(), ".mvn/wrapper/maven-wrapper.jar").toPath(),
+				new File(worktreeDir, ".mvn/wrapper/maven-wrapper.jar").toPath());
+		Files.copy(new File(rootFolder(), ".mvn/wrapper/maven-wrapper.properties").toPath(),
+				new File(worktreeDir, ".mvn/wrapper/maven-wrapper.properties").toPath());
+
+		// Create a pom.xml in the worktree
+		setFile("worktree/pom.xml").toLines(
+				"<project xmlns='http://maven.apache.org/POM/4.0.0' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xsi:schemaLocation='http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd'>",
+				"  <modelVersion>4.0.0</modelVersion>",
+				"  <groupId>test</groupId>",
+				"  <artifactId>test</artifactId>",
+				"  <version>1.0.0</version>",
+				"  <build>",
+				"    <plugins>",
+				"      <plugin>",
+				"        <groupId>com.diffplug.spotless</groupId>",
+				"        <artifactId>spotless-maven-plugin</artifactId>",
+				"        <version>" + System.getProperty("spotlessMavenPluginVersion") + "</version>",
+				"        <configuration>",
+				"          <formats>",
+				"            <format>",
+				"              <ratchetFrom>baseline</ratchetFrom>",
+				"              <includes>",
+				"                <include>" + TEST_PATH + "</include>",
+				"              </includes>",
+				"              <replace>",
+				"                <name>Lowercase hello</name>",
+				"                <search>HELLO</search>",
+				"                <replacement>hello</replacement>",
+				"              </replace>",
+				"            </format>",
+				"          </formats>",
+				"        </configuration>",
+				"      </plugin>",
+				"    </plugins>",
+				"  </build>",
+				"</project>");
+
+		// Verify that spotless works correctly in a git worktree
+		mavenRunner().withProjectDir(worktreeDir).withArguments("spotless:check").runNoError();
+	}
 }