java-gitignore

Java .gitignore

Overview

Two jobs: initialize a correct .gitignore for a Java project, and audit a repo that has already committed things it shouldn't. The expensive failure is a secret checked in — fixing the .gitignore after the fact does NOT remove it from history.

What MUST be ignored

Category	Patterns
Secrets / local config (the costly leak)	*.env, application-local.*, *-secret*.*, *.pem, *.p12, *.jks, *.keystore, credentials*, .envrc
Build output	target/, build/, out/, bin/, *.class
Packaged artifacts	*.jar, *.war, *.ear (except wrappers — below)
IDE files	.idea/, *.iml, *.ipr, *.iws, .vscode/, .settings/, .classpath, .project, .metadata, nbproject/
OS cruft	.DS_Store, Thumbs.db, Desktop.ini
Logs / crash dumps	*.log, hs_err_pid*, replay_pid*
Git/merge backups	*.orig, *.BACKUP.*, *.LOCAL.*, *.REMOTE.*

Drop in references/java.gitignore as a starting point (Maven + Gradle + IDE + OS + secrets).

What must NOT be ignored

• Wrapper files — keep gradle/wrapper/gradle-wrapper.jar, gradle/wrapper/gradle-wrapper.properties, and .mvn/wrapper/maven-wrapper.properties committed so ./gradlew / ./mvnw work for everyone. A broad *.jar or build/ rule can swallow these — add negations:

  !gradle/wrapper/gradle-wrapper.jar
  !**/src/main/**/build/
  

• Source, pom.xml/build.gradle, and .mvn/ config (other than timing.properties).

Initialize

1. One .gitignore at the repo root; module-specific files only if a module genuinely differs.

2. Copy references/java.gitignore, then trim to the project's build tool (Maven vs Gradle).

3. OS/IDE cruft is per-developer — a global excludes file keeps it out of every repo:

   git config --global core.excludesfile ~/.gitignore_global   # .DS_Store, .idea/, *.iml, etc.
   

Audit a repo (the handy part)

.gitignore only affects untracked files — anything already committed keeps being tracked even if it now matches a pattern. To find and fix what was checked in by mistake:

# List tracked files that SHOULD be ignored (already committed but match .gitignore)
git ls-files --cached --ignored --exclude-standard

# Un-track exactly those files WITHOUT deleting your working copy, then commit.
# Drive git rm from the list above (don't guess paths — a non-tracked path aborts the whole command):
git ls-files --cached --ignored --exclude-standard -z | xargs -0 git rm --cached
git commit -m "chore: stop tracking ignored files"

Files covered by a global excludes file (.idea/, .DS_Store) won't appear here — that's fine.

Sanity sweeps for common mistakes:

git ls-files | grep -E '\.(class|jar|war|log|iml)$|(^|/)(target|build|out|bin)/|\.idea/'
git ls-files | grep -iE 'secret|credential|\.env$|application-local|\.(pem|p12|jks|keystore)$'

Secrets already committed — important

git rm --cached removes a file from the current commit, not from history — the secret is still recoverable from earlier commits. If a real secret was committed:

1. Rotate the secret immediately (assume it's compromised). This is the only true fix.
2. Then scrub history with git filter-repo (or BFG), and force-push (coordinate with the team).
3. Add the pattern to .gitignore so it can't recur.

Red flags — stop

• target//build//.class/.idea/ showing up in git status as tracked
• A *.env, application-local.*, keystore, or credentials* file staged or committed
• A broad ignore (*.jar, build/) with no negation for the wrapper jar
• "I'll just git rm --cached the secret" — that doesn't remove it from history; rotate it