From 5f554385819556bc687621812e63125e0bd1fcb4 Mon Sep 17 00:00:00 2001 From: Gitea Actions Date: Wed, 19 Aug 2026 01:58:54 +0000 Subject: [PATCH] chore(docs): regenerate manual, man page, and component registry --- docs/fish-config.1 | 167 ++++++++++++++++++++++++++++++++++++++++- docs/fish-config.md | 179 +++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 342 insertions(+), 4 deletions(-) diff --git a/docs/fish-config.1 b/docs/fish-config.1 index afa0a9b..d95f870 100644 --- a/docs/fish-config.1 +++ b/docs/fish-config.1 @@ -2933,7 +2933,10 @@ across four pages, without having to type or remember variable names: path, and the user-dots convenience symlink toggle (Dots link) Toggle rows use ← / → (or h / l) to step OFF ← DEFAULT → ON; DEFAULT erases -the variable so the master switch / built-in default applies. Value rows +the variable so the master switch / built-in default applies. On the +Universal/Session pages, Enter on a category row (C1\[en]C6) opens that +category\[aq]s sub-category drill-down page for finer-grained toggles; +Escape backs out to the category list. Value rows (Sponge, Paths) use Enter to edit inline; ← / h clears to default. List rows (e.g. Extra secret, OK codes) accept values separated by commas and/or whitespace \[em] \[dq]A, B\[dq], \[dq]A,B\[dq] and \[dq]A B\[dq] all yield the same two entries. @@ -2962,7 +2965,10 @@ Navigation: ↑ ↓ / k j Move cursor ← → / h l Toggle rows: OFF ← DEFAULT → ON ← / h Value rows: clear to default - Enter Value rows: edit inline (Sponge / Paths pages) + Enter Category rows (Universal/Session): open sub-category + drill-down page. Value rows: edit inline (Sponge / + Paths pages) + Escape Sub-category page: back out to the category list Tab / S-Tab Next / previous page q / Escape Exit @@ -3831,6 +3837,21 @@ abbreviations, hooks) take effect in new shells. print an error naming the variable that disabled them. - On CachyOS, the distro fish config\[cq]s own aliases, history override, and bang-bang bindings are stripped per category as well. +.SS Sub-categories +.PP +Each of the six categories further sub-divides into two to six +sub-categories, each with its own +\f[V]__fish_config_op__\f[R] variable +(e.g.\ \f[V]__fish_config_op_aliases_filesystem\f[R]). +These follow the exact same truthy/falsy/unset cascade one level deeper: +an explicit sub-category value overrides the master switch and the +parent category\[cq]s setting, and an unset sub-category inherits from +its parent category (which in turn inherits from +\f[V]__fish_config_opinionated\f[R]). +Run config-settings and press Enter on a category row to browse and +toggle its sub-categories interactively. +See Components Reference for the full sub-category breakdown of every +category. .SS Prompt and Theme .SS Starship .PP @@ -3936,6 +3957,23 @@ C5 Logging and Capture \[em] Session logs, command duration C6 Greeting & First-Run UI \[em] Custom startup banner \f[R] .fi +.PP +Each category further sub-divides into two to six sub-categories (24 in +total) with their own +\f[V]__fish_config_op__\f[R] toggles \[en] see +that category\[cq]s page for its sub-category list. +.SS Per-function overrides: \f[V]C0\f[R]/\f[V]always\f[R] +.PP +Every guarded function or file can also carry a reserved +\f[V]always/on\f[R] or \f[V]always/off\f[R] tag in its +\f[V]# COMPONENT\f[R] header, independent of every C1-C6 category and +sub-category toggle and invisible to \f[V]config-settings\f[R]. +An \f[V]always/off\f[R] tag disables that function unconditionally; an +\f[V]always/on\f[R] tag enables it unconditionally, ignoring the state +of every other tagged sub-category. +This is a per-function escape hatch for cases too granular or too +idiosyncratic to justify a taxonomy entry \[en] edit the header directly +and run \f[V]__fish_config_op_registry_rebuild\f[R] to apply the change. .SS C1 \[em] Command Shadows .PP Disabling \f[V]__fish_config_op_aliases\f[R] restores standard system @@ -3971,6 +4009,35 @@ edit multi-editor launcher (GUI/term + fallbacks) $EDITOR/nvim/na When C1 is disabled, \f[V]rm\f[R] uses bare \f[V]command rm\f[R] with no wrapper \[em] files are permanently deleted, not trashed. There is no intermediate safety net. +.SS Sub-categories +.PP +\f[V]__fish_config_op_aliases\f[R] sub-divides into six sub-categories, +each with its own \f[V]__fish_config_op_aliases_\f[R] toggle: +.SS filesystem +.PP +\f[V]ls\f[R], \f[V]cat\f[R], \f[V]cd\f[R], \f[V]du\f[R], +\f[V]mkdir\f[R], \f[V]rm\f[R], \f[V]mv\f[R], and \f[V]cd\f[R]/zoxide +navigation \[en] the everyday filesystem-inspection and -modification +shadows. +.SS search +.PP +\f[V]rg\f[R], with its Kitty hyperlink formatting. +.SS network +.PP +\f[V]ping\f[R], \f[V]ssh\f[R], and \f[V]yt-dlp\f[R] \[en] shadows that +talk to the network. +.SS monitor +.PP +\f[V]top\f[R] -> \f[V]btop\f[R]. +.SS shell-tools +.PP +\f[V]bash\f[R] (XDG bashrc + \f[V]$SHELL\f[R] reset), \f[V]less\f[R] +(\f[V]$PAGER\f[R] fallback chain), and the \f[V]help config\f[R] +interception. +.SS dev-tools +.PP +\f[V]claude\f[R] (AGENTS.md/CLAUDE.md auto-linking) and \f[V]edit\f[R] +(multi-editor launcher), plus \f[V]agy\f[R]. .SS C2 \[em] Startup Side-Effects .PP These run automatically without any user action. @@ -4025,6 +4092,27 @@ The registry is machine-local at \f[V]$__fish_user_dots_path/auto-pull.list\f[R] (defaults to \f[V]\[ti]/.config/.user-dots/fish/auto-pull.list\f[R]) and is never committed. +.SS Sub-categories +.PP +\f[V]__fish_config_op_autoexec\f[R] sub-divides into five +sub-categories, each with its own +\f[V]__fish_config_op_autoexec_\f[R] toggle: +.SS plugin-management +.PP +Fisher bootstrap on first run. +.SS pkg-wrappers +.PP +\f[V]paru\f[R]/\f[V]yay\f[R] wrapper generation. +.SS venv +.PP +Automatic Python virtualenv activation. +.SS telemetry +.PP +The WakaTime hook\[cq]s startup bootstrap. +.SS sync +.PP +Auto-pull background fast-forward, and the user-dots convenience +symlink. .SS C3 \[em] Key and Environment Overrides .PP These change fundamental shell behavior: how keys work, which pager @@ -4064,6 +4152,24 @@ When C3 is disabled, \f[V]exit\f[R] falls back to \f[V]builtin exit\f[R] with no scrollback capture, no Kitty IPC, and no file I/O on exit. The scrollback capture block is independently controlled by C5 (see below). +.SS Sub-categories +.PP +\f[V]__fish_config_op_overrides\f[R] sub-divides into three +sub-categories, each with its own +\f[V]__fish_config_op_overrides_\f[R] toggle: +.SS key-bindings +.PP +Vi mode, autopair, puffer key intercepts, bang-bang history expansion, +and \f[V]smart_exit\f[R]\[cq]s plain-exit path. +.SS environment +.PP +\f[V]$PATH\f[R], \f[V]$PAGER\f[R]/\f[V]$EDITOR\f[R]/\f[V]$GPG_TTY\f[R], +and \f[V]$CDPATH\f[R]. +.SS prompt +.PP +Starship, the right prompt, Catppuccin syntax/prompt colors, and FZF +theming (\f[V]$FZF_DEFAULT_OPTS\f[R]) \[en] all driven by the same guard +as a single unit, not independently toggleable from each other. .SS C4 \[em] Terminal and Tool Integration .PP These features couple the shell to specific external tools. @@ -4090,6 +4196,27 @@ Disabled integration commands (\f[V]spwin\f[R], \f[V]tab\f[R], \f[V]split\f[R], \f[V]hist\f[R], \f[V]logs\f[R], \f[V]upgrade\f[R]) print a colored error to stderr naming the variable that disabled them rather than silently failing. +.SS Sub-categories +.PP +\f[V]__fish_config_op_integrations\f[R] sub-divides into five +sub-categories, each with its own +\f[V]__fish_config_op_integrations_\f[R] toggle: +.SS terminal-abbrs +.PP +The Kitty/WezTerm abbreviation set. +.SS window-mgmt +.PP +\f[V]spwin\f[R], \f[V]tab\f[R], \f[V]split\f[R]. +.SS notifications +.PP +\f[V]done\f[R]\[cq]s completion notifications, and the WakaTime activity +hook. +.SS history-logs +.PP +\f[V]hist\f[R], \f[V]logs\f[R]. +.SS pkg-upgrade +.PP +\f[V]upgrade\f[R]. .SS C5 \[em] Logging and Capture .PP Five components capture shell output to disk. @@ -4242,6 +4369,23 @@ Note: C3 and C5 compose independently. C3 controls whether the smart_exit wrapper is active at all; C5 controls only the scrollback-capture block inside it. With C3 disabled, exit is plain builtin exit regardless of C5. +.SS Sub-categories +.PP +\f[V]__fish_config_op_logging\f[R] sub-divides into three +sub-categories, each with its own +\f[V]__fish_config_op_logging_\f[R] toggle (all still opt-in by +default, inherited from C5\[cq]s own opt-in behavior \[en] see §3 of the +design spec): +.SS terminal-capture +.PP +Kitty watcher scrollback capture, and \f[V]smart_exit\f[R]\[cq]s +logging-guard path. +.SS multiplexer-capture +.PP +tmux \f[V]pipe-pane\f[R] and zellij \f[V]dump-screen\f[R] capture. +.SS pkg-logs +.PP +\f[V]paru\f[R]/\f[V]yay\f[R] AUR log wrappers. .SS C6 \[em] Greeting and First-Run UI .IP .nf @@ -4258,6 +4402,16 @@ fish_greeting override Empty function defined late in config.fish to When C6 is disabled, no greeting is printed by this config. Any greeting set by the distro or other configs runs normally \[em] this config simply does not override it. +.SS Sub-categories +.PP +\f[V]__fish_config_op_greeting\f[R] sub-divides into two sub-categories, +each with its own \f[V]__fish_config_op_greeting_\f[R] toggle: +.SS first-run +.PP +The first-run welcome banner. +.SS greeting-message +.PP +The per-session \f[V]fish_greeting\f[R] override. .SH 9. FISHER PLUGINS .PP Fisher is bootstrapped automatically on the \f[B]first interactive @@ -4887,6 +5041,15 @@ set -Ue __fish_config_opinionated \f[R] .fi .PP +Each category also has two to six sub-categories (e.g. +\f[V]__fish_config_op_aliases_filesystem\f[R]) that can be checked, +disabled, or reset the same way \[em] +\f[V]set -U __fish_config_op__ off\f[R] and +\f[V]set -Ue __fish_config_op__\f[R] work +identically to the category-level recipes above, just one level more +granular. +See Components Reference for the full list. +.PP For an interactive alternative to setting these variables by hand, run \f[V]config-settings\f[R]. .PP diff --git a/docs/fish-config.md b/docs/fish-config.md index 22c0d47..0f1e802 100644 --- a/docs/fish-config.md +++ b/docs/fish-config.md @@ -2366,7 +2366,10 @@ functions). They are active in all interactive sessions. path, and the user-dots convenience symlink toggle (Dots link) Toggle rows use ← / → (or h / l) to step OFF ← DEFAULT → ON; DEFAULT erases - the variable so the master switch / built-in default applies. Value rows + the variable so the master switch / built-in default applies. On the + Universal/Session pages, Enter on a category row (C1–C6) opens that + category's sub-category drill-down page for finer-grained toggles; + Escape backs out to the category list. Value rows (Sponge, Paths) use Enter to edit inline; ← / h clears to default. List rows (e.g. Extra secret, OK codes) accept values separated by commas and/or whitespace — "A, B", "A,B" and "A B" all yield the same two entries. @@ -2395,7 +2398,10 @@ functions). They are active in all interactive sessions. ↑ ↓ / k j Move cursor ← → / h l Toggle rows: OFF ← DEFAULT → ON ← / h Value rows: clear to default - Enter Value rows: edit inline (Sponge / Paths pages) + Enter Category rows (Universal/Session): open sub-category + drill-down page. Value rows: edit inline (Sponge / + Paths pages) + Escape Sub-category page: back out to the category list Tab / S-Tab Next / previous page q / Escape Exit @@ -2963,6 +2969,19 @@ NOTE: - Disabled integration commands (spwin, tab, split, hist, logs, upgrade) print an error naming the variable that disabled them. - On CachyOS, the distro fish config's own aliases, history override, and bang-bang bindings are stripped per category as well. +### Sub-categories + +Each of the six categories further sub-divides into two to six +sub-categories, each with its own `__fish_config_op__` +variable (e.g. `__fish_config_op_aliases_filesystem`). These follow the +exact same truthy/falsy/unset cascade one level deeper: an explicit +sub-category value overrides the master switch and the parent category's +setting, and an unset sub-category inherits from its parent category (which +in turn inherits from `__fish_config_opinionated`). Run config-settings and +press Enter on a category row to browse and toggle its sub-categories +interactively. See Components Reference for the +full sub-category breakdown of every category. + ## Prompt and Theme @@ -3044,6 +3063,21 @@ category variable. C5 Logging and Capture — Session logs, command duration C6 Greeting & First-Run UI — Custom startup banner +Each category further sub-divides into two to six sub-categories (24 in +total) with their own `__fish_config_op__` toggles +-- see that category's page for its sub-category list. + +## Per-function overrides: `C0`/`always` + +Every guarded function or file can also carry a reserved `always/on` or +`always/off` tag in its `# COMPONENT` header, independent of every C1-C6 +category and sub-category toggle and invisible to `config-settings`. An +`always/off` tag disables that function unconditionally; an `always/on` +tag enables it unconditionally, ignoring the state of every other tagged +sub-category. This is a per-function escape hatch for cases too granular +or too idiosyncratic to justify a taxonomy entry -- edit the header +directly and run `__fish_config_op_registry_rebuild` to apply the change. + ## C1 — Command Shadows Disabling `__fish_config_op_aliases` restores standard system behavior for @@ -3075,6 +3109,38 @@ all of these commands. When C1 is disabled, `rm` uses bare `command rm` with no wrapper — files are permanently deleted, not trashed. There is no intermediate safety net. +### Sub-categories + +`__fish_config_op_aliases` sub-divides into six sub-categories, each with +its own `__fish_config_op_aliases_` toggle: + +### filesystem + +`ls`, `cat`, `cd`, `du`, `mkdir`, `rm`, `mv`, and `cd`/zoxide navigation -- +the everyday filesystem-inspection and -modification shadows. + +### search + +`rg`, with its Kitty hyperlink formatting. + +### network + +`ping`, `ssh`, and `yt-dlp` -- shadows that talk to the network. + +### monitor + +`top` -> `btop`. + +### shell-tools + +`bash` (XDG bashrc + `$SHELL` reset), `less` (`$PAGER` fallback chain), +and the `help config` interception. + +### dev-tools + +`claude` (AGENTS.md/CLAUDE.md auto-linking) and `edit` (multi-editor +launcher), plus `agy`. + ## C2 — Startup Side-Effects These run automatically without any user action. Disabling @@ -3118,6 +3184,31 @@ branches, or repos without a remote. The handler fires once per repo entry (not on every sub-directory `cd`). The registry is machine-local at `$__fish_user_dots_path/auto-pull.list` (defaults to `~/.config/.user-dots/fish/auto-pull.list`) and is never committed. +### Sub-categories + +`__fish_config_op_autoexec` sub-divides into five sub-categories, each +with its own `__fish_config_op_autoexec_` toggle: + +### plugin-management + +Fisher bootstrap on first run. + +### pkg-wrappers + +`paru`/`yay` wrapper generation. + +### venv + +Automatic Python virtualenv activation. + +### telemetry + +The WakaTime hook's startup bootstrap. + +### sync + +Auto-pull background fast-forward, and the user-dots convenience symlink. + ## C3 — Key and Environment Overrides These change fundamental shell behavior: how keys work, which pager opens, @@ -3151,6 +3242,26 @@ When C3 is disabled, `exit` falls back to `builtin exit` with no scrollback capture, no Kitty IPC, and no file I/O on exit. The scrollback capture block is independently controlled by C5 (see below). +### Sub-categories + +`__fish_config_op_overrides` sub-divides into three sub-categories, each +with its own `__fish_config_op_overrides_` toggle: + +### key-bindings + +Vi mode, autopair, puffer key intercepts, bang-bang history expansion, +and `smart_exit`'s plain-exit path. + +### environment + +`$PATH`, `$PAGER`/`$EDITOR`/`$GPG_TTY`, and `$CDPATH`. + +### prompt + +Starship, the right prompt, Catppuccin syntax/prompt colors, and FZF +theming (`$FZF_DEFAULT_OPTS`) -- all driven by the same guard as a single +unit, not independently toggleable from each other. + ## C4 — Terminal and Tool Integration These features couple the shell to specific external tools. Disabling @@ -3173,6 +3284,31 @@ Disabled integration commands (`spwin`, `tab`, `split`, `hist`, `logs`, `upgrade a colored error to stderr naming the variable that disabled them rather than silently failing. +### Sub-categories + +`__fish_config_op_integrations` sub-divides into five sub-categories, +each with its own `__fish_config_op_integrations_` toggle: + +### terminal-abbrs + +The Kitty/WezTerm abbreviation set. + +### window-mgmt + +`spwin`, `tab`, `split`. + +### notifications + +`done`'s completion notifications, and the WakaTime activity hook. + +### history-logs + +`hist`, `logs`. + +### pkg-upgrade + +`upgrade`. + ## C5 — Logging and Capture Five components capture shell output to disk. Unlike every other category, @@ -3285,6 +3421,25 @@ Note: C3 and C5 compose independently. C3 controls whether the smart_exit wrapper is active at all; C5 controls only the scrollback-capture block inside it. With C3 disabled, exit is plain builtin exit regardless of C5. +### Sub-categories + +`__fish_config_op_logging` sub-divides into three sub-categories, each +with its own `__fish_config_op_logging_` toggle (all still opt-in +by default, inherited from C5's own opt-in behavior -- see §3 of the +design spec): + +### terminal-capture + +Kitty watcher scrollback capture, and `smart_exit`'s logging-guard path. + +### multiplexer-capture + +tmux `pipe-pane` and zellij `dump-screen` capture. + +### pkg-logs + +`paru`/`yay` AUR log wrappers. + ## C6 — Greeting and First-Run UI Component What it shows @@ -3298,6 +3453,19 @@ When C6 is disabled, no greeting is printed by this config. Any greeting set by the distro or other configs runs normally — this config simply does not override it. +### Sub-categories + +`__fish_config_op_greeting` sub-divides into two sub-categories, each +with its own `__fish_config_op_greeting_` toggle: + +### first-run + +The first-run welcome banner. + +### greeting-message + +The per-session `fish_greeting` override. + # 9. FISHER PLUGINS Fisher is bootstrapped automatically on the **first interactive session** via @@ -3740,6 +3908,13 @@ Re-enable everything: set -Ue __fish_config_opinionated +Each category also has two to six sub-categories (e.g. +`__fish_config_op_aliases_filesystem`) that can be checked, disabled, or +reset the same way — `set -U __fish_config_op__ off` +and `set -Ue __fish_config_op__` work identically to +the category-level recipes above, just one level more granular. See +Components Reference for the full list. + For an interactive alternative to setting these variables by hand, run `config-settings`. ---