anthropics / anthropics/claude-code

docs: hooks-guide auto-format example breaks on paths with spaces and exits 2 on unsupported files — contradicts the bundled update-config skill

Offen Anfängerfreundlich
#88,188 1 Kommentar 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
area:hooks bug documentation has repro
Vorherrschende Sprache
Python
Sterne
145k
Forks
23.1k
PR-Merge-Kennzahlen
PR-Kennzahlen ausstehend

Beschreibung

## Summary

The "Auto-format code after edits" example in [hooks-guide](https://code.claude.com/docs/en/hooks-guide#auto-format-code-after-edits) has two defects. It appears twice on the page and is the first hook pattern most people copy.

```json
"command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
```

Both failures are silent or noisy in ways that surface long after the user has stopped watching the hook.

## Defect 1 — `xargs` word-splits paths containing spaces

`xargs` splits on whitespace, so one file becomes several nonexistent paths.

```console
$ echo '{"tool_input":{"file_path":"/tmp/carpeta con espacios/a.ts"}}' \
| jq -r '.tool_input.file_path' | xargs printf '[%s]\n'
[/tmp/carpeta]
[con]
[espacios/a.ts]

$ echo '{"tool_input":{"file_path":"/tmp/carpeta con espacios/a.ts"}}' \
| jq -r '.tool_input.file_path' | xargs ls
ls: /tmp/carpeta: No such file or directory
ls: con: No such file or directory
ls: espacios/a.ts: No such file or directory
```

Control: with a path that has no spaces, `xargs` works correctly. The bug is therefore intermittent by nature — the hook appears to work for months until someone edits a file under `My Project/`.

The page contains **no** warning about spaces or word-splitting. Searched the full 71 KB of the rendered page: zero occurrences of `read -r`, and nothing about quoting near the example. The only related note is 900 lines away under troubleshooting ("command not found"), suggesting `"args": []` for exec form.

## Defect 2 — no `--ignore-unknown`, so unsupported files exit 2

`exit 2` is the _blocking error_ code for hooks: stderr is fed back to Claude.

```console
$ prettier --write s.py ; echo "exit=$?"
[error] No parser could be inferred for file ".../s.py".
exit=2

$ prettier --write --ignore-unknown s.py ; echo "exit=$?"
exit=0
```

The documented command has neither `--ignore-unknown` nor `|| true`. In any polyglot repository, every edit to a `.py`, `.sh`, `.toml`, or any file Prettier has no parser for makes the hook return a blocking error on an operation that succeeded.

## Defect 3 (minor) — `npx` can hit the network

`npx prettier` with no local copy resolves by downloading from the registry. On a machine whose global Prettier lives inside an nvm release, a Node version bump removes it from `PATH` and this hook silently starts fetching Prettier on every edit.

## This contradicts a bundled first-party source

The `update-config` skill that ships with Claude Code prescribes the opposite, explicitly:

> use `jq -r` into a quoted variable or `{ read -r f; ... "$f"; }`, **NOT** unquoted `| xargs` (splits on spaces)

Two official sources of the same product disagree, and the more visible one is the incorrect one.

## Suggested fix

```json
"command": "jq -r '.tool_response.filePath // .tool_input.file_path' | { read -r f; npx prettier --write --ignore-unknown \"$f\"; } || true"
```

- `read -r` into a quoted variable — no word-splitting
- `--ignore-unknown` — unsupported files are skipped silently instead of exiting 2 (also honours `.prettierignore`)
- `|| true` — a formatter should not turn a successful edit into a hook error
- `.tool_response.filePath` first, matching the fallback the `update-config` skill uses

A one-line note that paths may contain spaces would also help readers who adapt the pattern to other formatters.

## Environment

- Claude Code 2.1.237
- macOS (arm64), APFS
- Prettier 3.9.6
- `jq` via Homebrew

## Also worth checking

The page states "When the hook succeeds, Claude Code shows nothing in the conversation." In practice a `PostToolUse` hook that rewrites the edited file surfaces a `PostToolUse hook modified after your edit (likely a formatter)` notice. I have not isolated the exact conditions, so this is an observation rather than a confirmed claim — but the sentence may be worth revisiting, since that notice is genuinely useful and users are being told it does not exist.

Beitragsleitfaden

Für dieses Repository ist kein Beitragsleitfaden indexiert

Rechercherichtung

Start at the “Auto-format code after edits” example in hooks-guide, which appears twice, and compare it with the bundled update-config skill’s quoting guidance. Reproduce the reported space-containing path and unsupported-file cases, then update both copies so paths are preserved and unsupported files do not create blocking hook errors; verify the surrounding success wording against confirmed behavior.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
nodejs, shell
Bereich
documentation
Issue-Typ
Dokumentation
Schwierigkeit
2/5
Geschätzter Aufwand
1-3 Stunden
Aktivitätsstatus
Aktiv
Klarheit
Größtenteils klar
Anfängerfreundlichkeit
76/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.