Documents the branching/PR workflow, commit conventions, fish function
doc-header and colored --help conventions, the docs generation
pipeline, testing, and the secrets/machine-config placement rule, so
these practices live somewhere durable instead of only in commit
history and conversation memory.
Add the established c_head/c_cmd/c_flag/c_dim/c_arg color scheme to
--help (or usage-on-error) output in play-media and 13 other functions
that lacked it or used an ad hoc scheme: bkg, detach, replay, p, y,
spark, wake-lock, open-url, repo-open, dng2avif, dockup, fish-deps
(__fish_deps_help), and scrub.
Also tweak the standard itself:
- c_cmd now uses plain `set_color --bold` instead of `--bold white`,
so the command name adapts to the terminal's foreground instead of
forcing white text that washes out on light-background themes.
Applied across all functions already using the pattern.
- jobrunner's reset variable renamed from c_rst to c_reset to match
the naming used everywhere else.
A missing trailing backslash after the Thumbs.db:encryptable pattern
terminated the `set -l aggressive_patterns` array early. The AI-tool
patterns (.gemini*, .claude*, .antigravity*, .remember*) were then
executed as a bogus command instead of being appended to the array,
so scrub -a never actually purged them, and every scrub invocation
printed a spurious "Unknown command" error.
Fuzzy-filters audio/video files under the current directory via fd,
previews them with thumbnails pulled from the freedesktop thumbnail
cache (or ffprobe metadata as a fallback), and plays the selection
through the best available player: --player flag, $play_media_player,
xdg-mime default, then a short mpv/vlc fallback list. Adds mpv/vlc as
optional fish-deps entries.
The only other cd left in the workflow mixed two working directories
in one step: docs/build-manual.py --site runs from the repo root, then
npm ci/astro build need docs/site. Split into two steps so each can
use working-directory instead, keeping the whole file cd-free and
consistent with the Cloudflare deploy step's fix.
Gitea/GitHub Actions auto-groups a multi-line run: script under
"Run <first line>". With `cd docs/site` as the first line, the
collapsed log tree showed that instead of the actual wrangler deploy
command. Moving the directory change to the step's working-directory
key drops cd from the script entirely, so the group label now reflects
the command that's actually running.
workflow_dispatch already ran the whole pipeline manually, but there
was no way to fire just one job (e.g. re-run docs generation without
re-running the fish test suite) the way the old standalone
build-docs.yml let you. Add a job choice input (all/test/build-docs,
defaulting to all) and gate each job on it via `if:`, while leaving
the push-triggered path's needs: test gating untouched.
Two more sources of CI noise/fragility alongside the debconf frontend
fix: fish's install pulls in man-db/groff-base/xsel as recommends,
triggering a slow mandb rebuild for tooling nothing here uses;
--no-install-recommends skips that. apt-get update had no retry
policy, so a transient blip against the PPA mirror failed the whole
job; -o Acquire::Retries=3 gives it a few chances first.
apt-get install was probing for a Dialog then Readline debconf frontend
before falling back to Teletype on the non-interactive CI runner,
adding noise and failed-negotiation log lines to every run. Passing
DEBIAN_FRONTEND=noninteractive directly on the sudo command line (env
vars set via step-level `env:` don't survive sudo's env_reset) skips
the negotiation and goes straight to the frontend that actually works
here.
The @@ picker only listed files with no preview. It now lists both
files and directories via fd (matching _fzf_search_directory), and
shows a bat-highlighted or image-rendered preview through
_fzf_preview_file. Image previews use a kitty-graphics-protocol,
chafa, viu, timg fallback chain via the new _fzf_preview_image
helper, benefiting the Ctrl+F directory search and git-status
pickers as well since they share the same preview helper.
Adds tests/run-tests.fish (syntax lint over every .fish file, plus a
sandboxed interactive load) and tests/functional.fish (10 checks
covering XDG/PATH/CDPATH setup, key bindings, abbreviations, core
functions, exit rewiring, and the opinionated-component registry).
The sandbox copies config-relevant files into a scratch HOME/XDG tree
rather than symlinking the checkout, since this repo also serves as a
live ~/.config/fish and a symlink would let universal-variable writes
leak into the real fish_variables file.
Wires the suite into build-docs.yml as a `test` job that `build-docs`
now depends on, so a broken config can no longer get published to the
docs site. Documents the workflow in the README's new Testing section.
Binding the raw @@ chord made a lone @ an ambiguous prefix, so fish
(with fish_sequence_key_delay_ms unset) held every typed @ indefinitely
until a disambiguating keystroke arrived, breaking things like
`ssh user@host`. Binding the single @ key instead and checking whether
the current token is already a bare @ removes the ambiguity entirely:
plain @ always self-inserts instantly, and a second consecutive @
triggers the picker in place, with no forced delimiter before you can
keep typing. Vi's normal/visual modes are left unbound, matching their
existing (no-op) @ behavior.
Ubuntu 24.04's default repo only carries fish 3.7, but
docs/manual/06-dependency-catalog.md states fish >= 4.0 as a
project dependency. ppa:fish-shell/release-4 is the fish-shell
maintainers' own PPA and explicitly supports 24.04.
fish 3.7 (Ubuntu 24.04's packaged version, used in CI) rejects
'source /dev/stdin' when it's backed by a pipe, with
"'/dev/stdin' is not a file" -- fish 4.8 (local dev) accepts it.
Writing the generated registry to a real temp file sources
identically across fish versions.
The registry round-trip test spawns a real fish subprocess to verify
conf.d/__fish_config_op_registry.fish sources correctly, but the
runner image has no fish binary, so the workflow failed with
FileNotFoundError.
The wrapped description for the Enter key was indented one column past
every other description in the Navigation block. Drop the extra leading
space so it lines up at column 17 with the rest.
test_c0_tags_never_combine_with_contradiction_unwarned could never fail (its
own docstring said so) yet inflated the test_* pass count. Rename it to
warn_c0_tags_never_combine_with_contradiction, matching the file's existing
warn_* convention, and call it explicitly from main() alongside the other
three warn_* checks.
warn_functions_without_component also permanently false-positived on
functions/__fish_config_op_enabled.fish: the file's own function signature
and EXAMPLE prose contain the literal guard name, tripping the "calls the
guard" substring check against itself. Exclude the guard's own supporting
infrastructure files (__fish_config_op_enabled.fish,
__fish_config_op_cascade.fish, __fish_config_op_registry_lookup.fish) by
name -- an EXAMPLE-section-only exclusion wouldn't have worked here since
the false match is the function's own `function __fish_config_op_enabled`
definition line, not just its EXAMPLE block.
- Quote both keys and values in the generated __fish_config_op_registry.fish
keys array so a future identity/tag containing a glob-special character
(*, ?, [) can't be silently dropped by fish's set, desyncing the
positionally-paired keys/values arrays.
- Deduplicate the tag list per site in build_registry() so an identity
collision across sources (e.g. auto-pull tagged autoexec/sync in both
functions/auto-pull.fish and conf.d/auto-pull.fish) no longer produces a
duplicated tag in the committed registry.
- Add a comment to the generated file's header noting it must sort first
among conf.d/*.fish guard-callers, since that ordering is currently
implicit in the filename rather than stated anywhere.
- CI's auto-commit step now also stages conf.d/__fish_config_op_registry.fish
alongside the docs it already regenerates, so a # COMPONENT header change
pushed without a manual __fish_config_op_registry_rebuild self-heals
instead of silently drifting from what CI just regenerated.
Sub-categories were previously undocumented outside README and the
per-category reference pages. Add a paragraph to 07-customization.md (the
canonical opinionated-components page) explaining the sub-category cascade,
a short note to the 08-components-reference index pointing readers at each
category's sub-category list, and a troubleshooting note that
__fish_config_op_<category>_<subcategory> variables follow the same
check/reset pattern as category variables.
Bundled fix wave for six findings from the sub-category-granularity
whole-branch review:
- config-settings: reset in_subcat on Tab/Shift-Tab so up/down keep
routing to cur_row instead of freezing on the Sponge/Paths pages
after a drill-down
- verify-manual: _parsed_components() now delegates to
generate_component_registry.collect_components() instead of a
lossy dict.update() merge, closing a taxonomy-check blind spot on
identity collisions
- verify-manual: add test_committed_registry_matches_headers to
catch the committed registry drifting from current # COMPONENT
headers
- build-docs workflow: trigger on conf.d/** and config.fish edits,
not just functions/**
- __config_settings_draw_subcat: show (Universal)/(Session) in the
drill-down title so the persistence scope is visible before toggling
- __config_settings_draw / config-settings: mention the Enter
sub-category drill-down in the on-screen hint and --help text
- generate_component_registry: send the "wrote ..." progress line to
stderr so it no longer corrupts --concat's stdout output
Two bugs invisible to single-frame rendering, only reachable via the
interactive event loop:
- right/l and left/h resolved the sub-category variable name with
"$toggle_vars[(math ...)]"_(...) inside a quoted string -- fish
cannot expand a command-substitution index there ("Invalid index
value"), so the set never ran and varname silently kept the parent
category variable. Every arrow-key press on a sub-category row
toggled the parent category instead. Fixed by hoisting the category
variable into a plain local first, the same technique the down/j
case already used for its page index.
- __cs_dispatch_draw left panel_h fixed at 16 regardless of what it
actually drew, but the new sub-category page is n+7 lines (9-13,
always < 16). Every redraw/cleanup erase computed its height from
the stale constant, erasing too many rows and corrupting whatever
was above the panel. Fixed by having the dispatcher record the
actual printed height into panel_h after every draw, including
resetting it back to 16 on the value pages even when in_subcat is
stale from a Tab away without an intervening Escape.
Adds __config_settings_draw_subcat.fish, rendering a category's own
toggle plus its sub-category rows, sized dynamically from
__config_settings_subcats instead of the fixed 6-row category layout.
Wires the real per-category row count into config-settings.fish's
up/down handling (replacing Task 17's stub) and adds the
hyphen-to-underscore sub-category variable resolution to the
left/right toggle handlers, mirroring the translation the guard
function already applies.
Two box-drawing bugs surfaced while adapting the design doc's draft to
the real static sub-category data and were fixed rather than
transcribed: the title-dashes offset was off by 5, and several real
sub-category labels/descriptions (e.g. "Notifications", 13 chars;
several descriptions past 30 chars) exceed the narrower width tiers'
fixed field widths, so both fields are now defensively truncated
before padding to keep every row exactly iw+2 wide regardless of
content length.
overrides-tricks conflated two distinct C3 concerns under one shared site
(overrides/environment), so __fish_config_op_overrides_key_bindings off
left tricks.fish's bang-bang bindings active while abbr.fish/puffer.fish/
config.fish's equivalent sites correctly disabled -- a half-dismantled
bang-bang system per docs/manual's own atomic-gating claim. Split into
tricks-manpager (overrides/environment, matches PAGER/EDITOR/CDPATH) and
tricks-bang (overrides/key-bindings, matches abbr.fish/puffer.fish/
config.fish's bang-related sites, per
docs/manual/08-components-reference/03-c3-key-and-environment-overrides.md).
Also fixes stale prose in config.fish's top-of-file comment: the guard
signature is now <identity> [<site>], not <category>.
The site was mistagged aliases/filesystem in the prior commit. The original
code's own comment above the guarded block ("Surgically overriding the
distro config is opinionated (C3 overrides): skip it entirely when
overrides are disabled") documents this as an overrides decision, and it
gated __fish_config_op_overrides pre-migration. Retag to
overrides/environment (matching tricks.fish's own sibling site for the
equivalent action) so aliases=on/overrides=off keeps skipping
tricks.fish/ls/lt/cleanup/copy, as originally documented -- no silent
user-facing behavior change.
Adds multi-site `# COMPONENT` headers and converts every guard call site in
conf.d/tricks.fish, conf.d/abbr.fish, functions/smart_exit.fish,
conf.d/yay-wrapper.fish, conf.d/paru-wrapper.fish, conf.d/wakatime.fish,
conf.d/first_run.fish, and config.fish (9 sites across 3 categories) to the
self-identifying `(status current-function|basename) <site>` calling
convention. Regenerates conf.d/__fish_config_op_registry.fish.
__fish_config_op_enabled built the sub-category override variable name by
concatenating the tag's slug verbatim, e.g. __fish_config_op_integrations_window-mgmt.
Fish variable names cannot contain hyphens, so any hyphenated sub-category
slug (14 of the 24 in the taxonomy) silently could never be overridden --
an unset such variable safely fell through via set -q, but attempting to
set it always errored with "invalid variable name", masking the defect
since no prior smoke test exercised an explicit sub-category-level toggle.
The registry tag itself (as authored in # COMPONENT headers and the
taxonomy docs) stays hyphenated; only the derived fish variable name is
translated.
rootiest
Gitea Actions