feat(docs): add CLASSIFICATION function-header field, rename history shadow

Rename the C1 history() shadow to pretty-history so it never collides
with the fish builtin -- every function expecting stock history
semantics (search, --max, merge, ...) would otherwise silently break.
hist.fish, which relied on the shadow's timestamp formatting, now
requests it explicitly via builtin history --show-time.

Add a CLASSIFICATION doc-header label so a function can declare its
interaction with C1-shadowed commands (uses-shadow/bypasses-shadow)
and general hazards (destructive, network, blocking-prompt) for
anyone deciding to disable an opinionated category or call the
function from automation. Wired into the manual/site build pipeline
(manualtools.py, build-manual.py) and the C1 shadow doc gets a new
"For function authors" bypass-mechanism reference table
(command/builtin/__original_help, and which shadows have no real
bypass target at all).
This commit is contained in:
2026-09-21 21:26:40 -04:00
parent 392e6593ac
commit aef686af86
5 changed files with 82 additions and 6 deletions
+6 -4
View File
@@ -97,11 +97,13 @@ if __fish_config_op_enabled (status basename) tricks-bang
end
end
# Fish command history override to show timestamps
# Shadowing the history command is opinionated (C1 aliasing); when disabled,
# the function is never defined and fish's stock history behavior applies.
# Timestamped history view. Named pretty-history (not history) so it never
# shadows the fish builtin -- every function in this config that expects
# stock `history` semantics (search, --max, merge, ...) would otherwise
# silently break, which has happened more than once. Opinionated (C1
# aliasing); when disabled, the function is never defined.
if __fish_config_op_enabled (status basename) aliases-tricks
function history
function pretty-history --description 'History with timestamps prepended to every entry'
builtin history --show-time='%F %T '
end
end