setup-gitignore— agent skill

Initialize or idempotently revise the current repo's .gitignore — never the global excludesfile.

Scope

Per-repo only. Never read or write ~/.gitignore, ~/.config/git/ignore, or run git config --global. The user's global excludesfile handles cross-machine noise; this skill handles language/tool specifics for the current repo.

Sources composed (in order)

1. gitignore.io — templates keyed by detected language/framework (requires network)
2. AI tooling — bundled patterns from references/AI-TOOLING.md
3. IDE / editor — bundled patterns from references/IDE-EDITOR.md
4. Empirical — untracked paths from git status, confirmed interactively

Workflow

1. Detect repo root

git rev-parse --show-toplevel

Abort with a clear error if not inside a git repo.

2. Detect languages

Read references/LANGUAGE-DETECTION.md for the manifest → gitignore.io key table. Scan manifests:

fd --max-depth 2 -t f

Match filenames against the detection table; build a comma-separated key list (e.g., rust,node,typescript). If no manifests detected, use an empty key list (bundled blocks still apply).

3. Snapshot existing .gitignore

If .gitignore exists, snapshot it before any modification:

cp .gitignore /tmp/gitignore-snapshot-$(date +%s).bak

4. Surface empirical noise

git status -s -uall | rg '^\?\?' | rg -v '^\?\? \.gitignore'

Cluster untracked paths by top-level directory or extension. Present clusters to the user and wait for explicit confirmation. Do not add any empirical pattern without confirmation.

5. Compose

Run scripts/compose-gitignore.sh <csv> to fetch and merge gitignore.io templates. If the network call fails, tell the user and ask whether to continue with bundled-only mode.

Append the bundled blocks after the API output in order:

# === AI TOOLING ===
<contents of references/AI-TOOLING.md>

# === IDE / EDITOR ===
<contents of references/IDE-EDITOR.md>

# === EMPIRICAL ===
<user-confirmed patterns, one per line>

6. Merge or init

• No existing `.gitignore`: write the composed output directly.
• Existing `.gitignore`: merge each # === SECTION === block idempotently — patterns already present in the file are deduplicated (first occurrence wins). Preserve all user content outside section headers. Show the full diff via difft; write only after user confirms.

7. Verify

git status -s -uall | rg '^\?\?' | wc -l

Report untracked count before and after. List any paths still untracked so the user can decide whether to add further patterns.

Idempotence contract

Re-running the skill on a repo where the skill already ran produces no diff. Section headers act as stable merge anchors. User content outside sections is never modified.