[Pankraz76]

Closes #2443

Why

Spotless picks files with globs (target '**/*.md', <include>src/**/*.java</include>). Broad globs easily pick up files that are not part of the project's source: generated code, node_modules, local scratch files, IDE output. These are already listed once, in .gitignore. Today users have to copy those rules into targetExclude / <excludes> and keep both lists in sync. Even then they can't express negations (!keep.log) or nested .gitignore files. The workaround in the issue thread shells out to an npm tool to turn .gitignore into globs, which shows how much this is wanted (6 👍).

What

One opt-in flag in both build plugins, off by default:

Gradle

spotless {
  respectGitignore()            // all formats
  format 'misc', {
    target '**/*.md'
    respectGitignore(false)     // per-format override
  }
}

Maven

<configuration>
  <respectGitignore>true</respectGitignore>     <!-- all formats -->
  <formats>
    <format>
      <respectGitignore>false</respectGitignore> <!-- per-format override -->

Same rules as git status

A file is skipped only if both are true:

• it matches a pattern from any .gitignore (root or nested), .git/info/exclude, or core.excludesFile
• it is not tracked in the index

Tracked files are always formatted, even if they match an ignore pattern. That is how git behaves, and it avoids silently dropping committed sources from formatting.

Behaviour details

• Off by default, so no existing build changes.
• The format-level setting overrides the global one (same model as ratchetFrom).
• Works together with ratchetFrom (a Maven test covers this).
• Outside a git repository the build fails fast with: Respecting .gitignore requires a git repository, but none was found in ….
• Gradle: the filter is applied to the task's input FileCollection, so up-to-date checks see the filtered set. It is configuration-cache safe: the computed git state is transient, so it is recomputed every build and .gitignore edits take effect on the next run. Tested with the configuration cache on and off.

How

• lib-extra: new GitIgnoredFiles.
  • Uses a JGit IndexDiff (index vs. working tree, no HEAD needed), limited to the project subtree, and reads getIgnoredNotInIndex().
  • JGit reports a fully ignored directory as a single entry and does not descend into it, so large ignored folders (node_modules, build) cost almost nothing.
  • A lookup checks the file and its parent directories against that set.
  • The state is computed lazily, once per instance, and is thread-safe. The class is Serializable with transient state.
  • It reuses GitWorkarounds to find the repository, so git worktrees are handled the same way as for ratchetFrom.
• plugin-maven: a respectGitignore parameter on the mojo and on FormatterFactory. Filtering happens in collectFiles, after include/exclude (and ratchet) resolution.
• plugin-gradle: respectGitignore() / respectGitignore(boolean) / setRespectGitignore / isRespectGitignore on SpotlessExtension and FormatExtension. setupTask wraps the target in FileCollection.filter(...) with a small serializable Spec.

Tests

Written test-first: each suite was run red against an API-only stub or missing DSL, then made green.

Area	Test class	Scenarios	Result
Core	GitIgnoredFilesTest	root pattern; non-matching file; file deep in ignored dir; negation !keep.log; tracked-but-matching is not ignored; nested .gitignore scoping; .git/info/exclude; core.excludesFile; subproject root inherits repo rules; file outside root; not a git repo → clear error; serialization round-trip	12/12 ✅
Maven	RespectGitignoreTest	default unchanged; global skip on check + apply; non-ignored files still fixed; format-level flag; format false overrides global true; combined with ratchetFrom	6/6 ✅
Gradle	RespectGitignoreTest	same matrix, plus .gitignore edited between builds and the not-a-repo error; parameterized with configuration cache on and off	11/11 ✅

Also run:

• spotlessCheck and SpotBugs for lib-extra, plugin-maven, plugin-gradle ✅
• Existing suites around file collection, git and caching:
  • lib-extra: GitRachetMergeBaseTest, GitAttributesTest, GitWorkaroundsTest, all ✅ (34/34 including the new tests)
  • plugin-gradle: GitRatchetGradleTest, ConfigurationCacheTest, TargetExclude*, MultipleTargetsTest, UpToDateTest, MultiProjectTest, GradleIncrementalResolutionTest, all ✅ (47/47; ConfigurationCacheTest passed on rerun after Maven Central rate-limited a download)
  • plugin-maven: GitRatchetMavenTest, IncludesExcludesTest, MultipleFormatsTest, SpotlessCheckMojoTest ✅ (23/27)
• The 4 remaining Maven failures (SpecificFilesTest ×3, MultiModuleProjectTest.testConfigurationDependency) are pre-existing. They fail the same way on unmodified main (7cc923d), with google-java-format(java.lang.reflect.InvocationTargetException) in my environment (JDK 21), and are unrelated to this PR.

Out of scope / possible follow-ups

• In Gradle, each format with the flag computes its own IndexDiff for the project subtree. This is cheap because ignored directories are skipped, but it could be shared per project later if anyone measures a hot spot.
• Files inside a nested repository (submodule) under the project are checked against the outer repository's rules.

Checklist (from the PR template)

• Allow edits from maintainers
• [Unreleased] entries in CHANGES.md, plugin-gradle/CHANGES.md, plugin-maven/CHANGES.md (linking Support .gitignore #2443)
• README sections for both plugins ("How can I skip files ignored by git?") + TOC entries

🤖 Generated with Claude Code

https://claude.ai/code/session_01MTr23vs1UZzH1yBNJUacfL

[nedtwigg]

I'm leaning against merging this, although it's a great implementation. Here is my reasoning:

• specifying a tight target is plan A. If you do that, you get the best performance, and it's a small API
• you can targetExclude some stuff. This is plan B, performance isn't quite as good as just being more specific with your target, but it's still a pretty simple mental model
• targetExcludeUsingGitignore() is reasonable. The problem is
  • almost everyone wants to exclude things they are gitignoring
  • but a better way to accomplish that is to be specific with your target
  • and if there's a mode "targetExcludeUsingGitignore" then everyone is going to think they should turn it on, which will make Spotless slower on net, as compared to just being more specific with your target, which is not hard to do

Thumbs up on this comment if you agree and think gitignore is an unnecessary feature, thumbs down on this comment if you disagree and want this PR merged.

[Pankraz76]

Thanks for the honest take. I reworked the PR into the narrowest form of the idea, so the decision is about the feature itself and not about this implementation:

• Per format only. Gradle: targetExcludeUsingGitignore() on a format. Maven: <excludeUsingGitignore>true</excludeUsingGitignore> on a format. The global switch is gone, so there is no one-liner that turns it on for a whole build.
• Cheaper. GitIgnoredFiles now does a plain TreeWalk over index and working tree instead of an IndexDiff. It only lists directories and evaluates ignore rules, and skips ignored directories without tracked files.
• Shared. In Gradle the result lives in SpotlessTaskService: one walk per project per build, no matter how many formats use it. Maven does one per module.
• Documented as plan C. Both READMEs now say: tight target first, then targetExclude (which prunes the walk since targetExclude("**/build/**") makes configuration cache store and reuse walk the entire project directory #3147), and this only when the ignored files can't be described with a few globs. They also say plainly that it is the slowest option.
• Merged current main; CI is green.

What this does not change: it is still strictly slower than a tight target, because the files are found by target first and filtered afterwards. And your main point stands, people may reach for it out of habit. What it buys is correctness for the cases globs can't express (negations like !keep.log, nested .gitignore, .git/info/exclude), which is what #2443 asks for.

I'm fine either way. If you feel the docs can't keep people on plan A, feel free to close this. It would help to hear from the people who upvoted #2443 whether a tight target plus targetExclude already covers their case, or whether they really need git's rules.