---
source_keys:
  - context7-pre-commit-com
  - pre-commit-com
---

# Modifying an existing `.pre-commit-config.yaml`

Reached from `SKILL.md`'s Route table when the repo already has a config. Self-contained — the
create flow's file is not needed here. `SKILL.md`'s three common gates still apply.

Read the existing `.pre-commit-config.yaml` before editing. Note any stale `rev` values (see
**Rev staleness** below) but do not change them.

## Adding a hook

1. Run a shallow extension scan, so the addition is judged against the languages actually present:

   ```bash
   git ls-files | grep -oE '\.[a-z]+$' | sort | uniq -c | sort -rn
   ```

2. Read `references/hooks-by-language.md` for the correct repo URL, `rev` and recommended args
   before writing anything.

3. Check for duplicates. If the same hook ID, or an equivalent tool, is already configured, say so
   and stop rather than adding a second one.

4. To sanity-check a hook against the repo's real files before committing to it, smoke-test it:

   ```bash
   pre-commit try-repo <repo-url> <hook-id> --verbose
   ```

   Use a local path in place of the URL for a hook under development. This runs the hook without
   writing anything.

5. If the hook's source repo is already a block in the config, add the hook under that block.
   Otherwise append a new repo block.

6. State the proposed addition, wait for confirmation, write, and run `pre-commit validate-config`.
   On a non-zero exit, show the error, fix it, and re-validate.

## Removing a hook

1. Identify the hook entry and its parent repo block.

2. State what will be removed — the hook ID, and whether the parent repo block goes with it because
   it would be left with zero hooks. Wait for confirmation.

3. Remove the hook entry. If the repo block now has no hooks left, remove the whole block: an empty
   `hooks: []` fails `validate-config`.

4. Write, then run `pre-commit validate-config`. On a non-zero exit, **revert the edit**, show the
   error, and stop. A removal is not safely fixable in place the way a malformed new hook block is,
   so recovering the prior state beats patching forward.

## Configuring top-level keys

Only when the user explicitly asks. Valid keys: `fail_fast`, `default_stages`,
`default_language_version`, `minimum_pre_commit_version`, `exclude`, `files`,
`default_install_hook_types`.

State the proposed change and wait for confirmation before writing.

## Rev staleness

For each repo in the config that also appears in `references/hooks-by-language.md`, compare the
two `rev` values. Flag a mismatch as potentially outdated and tell the user to run `pc-run` to
autoupdate. Repos absent from the reference cannot be checked — skip them silently. Do not modify
any `rev` yourself.

The reference table's own pins go stale between updates, so treat a mismatch as a prompt to check
rather than proof of staleness. `pre-commit autoupdate`, via `pc-run`, is the authoritative answer
to what the current `rev` actually is.