configuring-git-hygiene · diff
git:20260716.29b4d22 to git:20260928.b87f747
32 added, 73 removed. Audit A to A.
---
description: 'Configure safe git workflow hygiene: pre-commit/pre-push hooks, Gitleaks
secret scanning, .gitignore rules, local git config, and guardrails. Use when setting
up git hooks, gitleaks/git leaks, staged pre-commit checks, pre-push validation,
core.hooksPath, .gitignore, or git config best practices. NOT for creating commits
(use committing-code), cleaning branches/worktrees (use cleanup-git), or creating
worktrees (use using-git-worktrees).'
name: configuring-git-hygiene
---
# Configure Git Hygiene
- Set up project-local git hygiene. Keep hooks fast enough to stay enabled. Do not overwrite hooks, change global config, remove tracked files, or install tools without user approval.
-
- ## Scope
-
- Use this skill for:
+ Set up project-local hygiene that stays fast enough to keep enabled. Stop if the directory is not a git repo.
- - Git hook setup or migration to a project hooks directory.
- - Staged-file pre-commit checks.
- - Full pre-push validation.
- - Gitleaks secret scanning.
- - `.gitignore` rules and tracked-file cleanup.
- - Local git config such as `core.hooksPath`, `includeIf`, signing, pull behavior, and pruning.
+ ## Ask first
- Do not use this skill for:
+ Propose the plan (current facts, files and config to change, verification, risks) and get approval before you:
- - Commit grouping or commit messages — use `committing-code`.
- - Worktree creation — use `using-git-worktrees`.
- - Branch/worktree cleanup — use `cleanup-git`.
+ - write, replace, or merge into a hook file;
+ - set a `git config` value (local or global) or run `chmod`;
+ - run `git rm --cached`;
+ - install a tool, or choose whether a hook fails or skips when a tool is missing.
- ## Step 1: Inspect Current State
+ If the repo is dirty, show `git status --short` and ask before hook or config edits.
- Run read-only checks first:
+ ## Inspect
```bash
- git rev-parse --show-toplevel
git status --short
git config --show-origin --get core.hooksPath || true
git config --show-origin --list | rg '^(file:.*\s+)?(user\.|commit\.|tag\.|pull\.|fetch\.|rerere\.|core\.hooksPath|includeIf\.)' || true
git ls-files .gitignore .pre-commit-config.yaml .gitleaks.toml 2>/dev/null || true
ls -la .git/hooks .githooks scripts/git-hooks 2>/dev/null || true
```
- If a hook framework already exists, extend it. Do not replace it.
-
- ## Step 2: Load Focused References
-
- - Hook files or `core.hooksPath` changes: read [hooks.md](references/hooks.md).
- - Gitleaks setup or secret scanning: read [gitleaks.md](references/gitleaks.md).
- - `.gitignore` or `git rm --cached`: read [gitignore.md](references/gitignore.md).
-
- ## Step 3: Propose Before Editing
-
- State current facts, proposed files/config, verification, and risks. Ask before:
-
- - writing or replacing hook files
- - running `git config --local` or any global config command
- - running `chmod`
- - running `git rm --cached`
- - choosing skip-vs-fail behavior for missing tools
+ ## Policy
- ## Step 4: Apply Safely
+ - Extend the existing hook framework. Without one, use `pre-commit`, then a project-local `core.hooksPath` directory (`git config --local core.hooksPath scripts/git-hooks`).
+ - Pre-commit runs only on staged or affected files: format, lint, touched-config validation, staged Gitleaks scan. No full tests, full builds, installs, or network calls.
+ - Pre-push runs the full build, test, type, and lint validation, plus a broader secret scan when practical.
+ - Run Gitleaks with `--redact`, and keep secret values out of chat and external tools.
+ - Hooks never auto-commit or restage files unless the repo already does.
+ - A hook that blocks legitimate work gets tuned; `--no-verify` is not the fix.
+ - `.gitignore` patterns come from real artifacts and stay narrow.
- Rules:
+ Details by topic:
- - Prefer existing project convention, then `pre-commit`, then project-local `core.hooksPath`.
- - Use project-local config for shared repos: `git config --local core.hooksPath scripts/git-hooks`.
- - Keep pre-commit staged/affected-file only; do not run full tests, full builds, installs, or network calls there.
- - Put full build/test/type/lint validation in pre-push.
- - Redact secret-scan output. Never paste secret values into external tools.
- - Use narrow `.gitignore` patterns derived from actual artifacts.
- - Do not auto-commit from hooks unless the project already has that convention.
+ - Hook scripts and pre-push input → [hooks.md](references/hooks.md)
+ - Gitleaks commands, missing tool, false positives → [gitleaks.md](references/gitleaks.md)
+ - `.gitignore` and untracking files → [gitignore.md](references/gitignore.md)
- ## Step 5: Verify
+ ## Verify
- Run the narrowest proof for the changed component:
+ - Hooks path: `git config --local --get core.hooksPath`, then run the hook directly on safe fixture input.
+ - Gitleaks: a staged or repo scan with `--redact`, when installed.
+ - `.gitignore`: `git check-ignore -v <path>` and `git ls-files <path>`.
+ - Hook scripts: the project's shell lint, format, and test gates.
- - Hook path/config: `git config --local --get core.hooksPath` and direct hook execution with safe fixture input when possible.
- - Gitleaks: staged or repo scan command with `--redact` when the tool is available.
- - `.gitignore`: `git check-ignore -v <path>` and `git ls-files <path>` for affected files.
- - Hook scripts: project shell lint/format/test gate when available.
+ Done when the relevant build/test/lint checks pass on what you changed, or you name each check that did not run and why.
## Output
```text
GIT HYGIENE CONFIG
- ==================
Scope: hooks | gitleaks | gitignore | config | guardrails
Status: PROPOSED | APPLIED | BLOCKED
-
- Current state:
- - <facts from git config/files>
-
- Plan:
- - <change and why>
-
- Changes:
- - <file/config edited>
-
- Verification:
- - <command> — pass/fail/not run
-
- Next:
- - <install tool, run hook, or push validation>
+ Current state: <facts from git config/files>
+ Plan: <change and why>
+ Changes: <file/config edited>
+ Verification: <command> — pass/fail/not run
+ Next: <install tool, run hook, or push validation>
```
- ## Failure Handling
-
- - Not a git repo: say so and stop.
- - Existing hook would be overwritten: stop and merge manually.
- - Tool missing: ask whether the hook should fail closed or skip with a clear message.
- - Dirty repo before hook/config edits: show `git status --short` and ask before proceeding.
- - Hook blocks legitimate work: diagnose and tune the hook; do not recommend `--no-verify` as the fix.