Gitignore

---
name: gitignore
description: Generate or repair a .gitignore tailored to the project's actual stacks, frameworks, OS, and editors, and untrack files that are already committed but should be ignored. Flags secrets/build/dependency files that slipped into the repo. Use when creating, fixing, or auditing .gitignore.
argument-hint: "(optional) stack/framework to target, or 'audit'"
---

Produce a `.gitignore` that fits *this* repo (driven by the stacks actually present, not a generic blob) and fix the common failure where a pattern is added but the file is already tracked, so Git keeps it anyway.

## Hard rules: never break these

- **Never ignore source.** Ignore dependencies, build output, caches, logs, secrets, and local cruft, never the code or config the project needs to build.
- **Adding a pattern does not untrack a tracked file.** `.gitignore` only affects *untracked* files. Already-committed files need `git rm --cached` (Step 5) to stop being tracked.
- **Preserve existing intent.** Don't wipe a hand-tuned `.gitignore`; merge, dedupe, and organize. Keep custom and negation (`!`) rules unless they're clearly wrong.
- **Treat tracked secrets as an incident.** A committed `.env`, key, or credential is already in history; adding it to `.gitignore` and `rm --cached` stops *future* tracking but does **not** remove it from past commits. Flag it loudly and point to history-rewrite tooling (`git filter-repo`, BFG) and secret rotation.
- **Confirm before `git rm --cached`.** It changes what's tracked and lands in the next commit.

## Step 1: Detect the stacks

Scan the repo for what's actually in use rather than guessing:

- **Manifests → ecosystem:** `package.json` (Node), `Cargo.toml` (Rust), `pyproject.toml`/`requirements.txt`/`Pipfile` (Python), `go.mod` (Go), `pom.xml`/`build.gradle` (Java/Kotlin), `Gemfile` (Ruby), `composer.json` (PHP), `*.csproj`/`*.sln` (.NET), `pubspec.yaml` (Dart/Flutter), `mix.exs` (Elixir).
- **Frameworks** (they add their own build/cache dirs): Next.js (`.next/`), Nuxt (`.nuxt/`), Astro, SvelteKit, Vite (`dist/`), Angular, Django (`*.sqlite3`, `staticfiles/`), Rails, Terraform (`.terraform/`), etc.
- **OS files:** macOS (`.DS_Store`), Windows (`Thumbs.db`, `Desktop.ini`), Linux (`*~`).
- **Editors/IDEs:** `.vscode/`, `.idea/`, `*.swp`, `.fleet/`; these typically belong in a *global* gitignore, but include locally if the team standardizes there.
- **Tooling:** test coverage (`coverage/`, `.nyc_output/`), env files (`.env*`), local caches (`.cache/`, `.turbo/`, `__pycache__/`).

## Step 2: Audit what's already tracked

- Read the current `.gitignore`(s); there may be nested ones in subdirectories.
- Find files that are tracked but shouldn't be: compare `git ls-files` against the patterns you intend (look especially for `node_modules/`, `dist/`/`build/`, `target/`, `__pycache__/`, `*.log`, `.env*`, key material `*.pem`/`*.key`/`id_rsa`).
- `git status --ignored` shows what's currently ignored vs. not.
- Anything sensitive already tracked → escalate per the hard rules.

## Step 3: Build the patterns

Compose sections per detected stack. Cover, for each:

- **Dependencies**: `node_modules/`, `vendor/`, `target/`, `.venv/`, `Pods/`.
- **Build output**: `dist/`, `build/`, `out/`, `*.pyc`/`__pycache__/`, `*.class`, `bin/`, `obj/`.
- **Env & secrets**: `.env`, `.env.*` (but **keep** `!.env.example`), `*.pem`, `*.key`, `*.p12`, `credentials.json`.
- **Logs & caches**: `*.log`, `.cache/`, `.turbo/`, `.gradle/`, `.pytest_cache/`.
- **Coverage**: `coverage/`, `.nyc_output/`, `htmlcov/`.
- **OS / editor**: per Step 1.

Use the canonical templates as reference (GitHub's `github/gitignore`, gitignore.io / Toptal generator) but tailor; don't dump every language. Prefer anchored, specific patterns (`/dist/` for a root-only dir) over broad ones that may catch wanted files.

## Step 4: Write / repair the file

- Group with section comments (`# Dependencies`, `# Build output`, `# Env & secrets`, …) for maintainability.
- Deduplicate and remove contradictions; keep legitimate custom and `!` negation rules.
- Don't over-ignore: if a glob would swallow a needed file (e.g. a committed `config/*.json`), add a negation (`!config/required.json`) or tighten the pattern.
- Layer correctly: root `.gitignore` for repo-wide rules; nested `.gitignore` only where a subtree needs its own; suggest a personal **global** gitignore (`core.excludesFile`) for editor/OS noise rather than imposing it on the repo.

## Step 5: Untrack already-committed files (with confirmation)

Editing `.gitignore` won't stop tracking files Git already knows about. For each such file/dir, after confirming:

```
git rm -r --cached path/to/thing      # removes from tracking, keeps it on disk
```

Then it stays on disk but drops out of the repo on the next commit. For tracked secrets, also flag history rewrite + credential rotation; `rm --cached` alone leaves them in every past commit.

## Step 6: Verify

- `git status --ignored`: intended files now show as ignored; nothing wanted is being ignored.
- `git check-ignore -v <path>`: explains which rule matches a given path (great for debugging surprises).
- Confirm source and required config still appear in `git status`/`git ls-files`.

Report the stacks detected, what got newly ignored or untracked, and any secrets/artifacts that need follow-up beyond `.gitignore`.