repo-hygiene — Version Control Hygiene

When to use

• About to commit and want to confirm nothing improper slipped in.
• "gitignore rule added but it's not working".
• Found third-party code / decompiled artifacts / nested repos / large files / secrets / personal local config in the repo.
• Before starting new dev, confirm the repo is clean.

When NOT to use

• Active feature work — this is end-of-work cleanup, not in-flight changes.
• Pure formatting / linting issues — use the appropriate tools.

Output

A clean repo: no improperly committed content, reasonable commit granularity, ignore rules working correctly.

The core gotcha (memorize this first)

Ignore rules only affect untracked files. Adding ignore to an already-tracked file has no effect — you must first remove it from tracking (keeping the local copy) and then add ignore.

This is the most common cause of "gitignore not working": the file was committed long ago, and a rule added after the fact cannot block a file already tracked.

Methodology

1. Identify content types that should not be in the repo

2. Layered verification tools (use as needed)

• status — change overview.
• check-ignore <path> — whether the path is blocked by some ignore rule (no output = not blocked).
• ls-files <path> — whether the path is already tracked (output = tracked, ignore has no effect on it).
• status -uall — expand collapsed untracked directories (regular status collapses directories containing non-ASCII paths or all-untracked content).

To judge whether adding ignore will help: first run ls-files to see if the file is tracked. Tracked → ignore won't work, go to step 4 to remove from tracking. Untracked → ignore works directly.

3. Inspect the ignore rules themselves

• Wrong path syntax (extra prefix characters, wrong case, wrong slash direction) — incorrect rules fail silently.
• Use trailing slash path/ for directories, no trailing slash for files.

4. Disposition

5. Commit granularity

Code / docs / config / cleanup go in separate commits so history is clear and each can be reverted independently. Avoid one giant commit mixing all types.

6. Pre-dev cleanliness check

• Working tree clean (no uncommitted changes).
• No untracked files waiting to be added (except local references).
• No dangling gitlinks.
• Ignore rules correct (improperly committed content removed from tracking).

Red lines (reasoned, not absolute)

• Do not run git add . (stage everything) without checking first — it sweeps improperly committed content (especially large files / third-party code) into the commit.
• Do not just add ignore without removing from tracking — for already-tracked files, ignore alone has no effect (the core gotcha).
• Do not physically delete local files for cleanup — use "remove from tracking, keep local" (git rm --cached), not actual deletion.

Worked example: one repo slim-down (sanitized)

1. After adding ignore rules, the decompiled directory still showed up → ls-files revealed it was already tracked (~14,000 files) → ignore was ineffective.
2. The original ignore rule had an extra character in the path prefix causing silent failure → fixed the rule.
3. A nested repo (peer code cloned in) was committed as a dangling gitlink → removed from tracking + ignore (kept local as reference).
4. Personal local permission config (.local) kept changing → removed from tracking + ignore.
5. Split into multiple commits: code / docs / cleanup separated.

This is one instance, not the methodology itself.