From 9d1acf0fb3aca2af7427df3e7fb406b9e7abd3b3 Mon Sep 17 00:00:00 2001 From: Gitea Actions Date: Tue, 28 Jul 2026 03:31:21 +0000 Subject: [PATCH] chore(docs): regenerate manual and man page --- docs/fish-config.1 | 171 ++++++++++++++++++++++----------------------- 1 file changed, 84 insertions(+), 87 deletions(-) diff --git a/docs/fish-config.1 b/docs/fish-config.1 index 2823e7b..dbe1197 100644 --- a/docs/fish-config.1 +++ b/docs/fish-config.1 @@ -50,14 +50,15 @@ directly. A production-grade Fish shell configuration targeting Fish 4.x. It provides: .IP \[bu] 2 -Drop-in replacements for common Unix tools (ls, cat, rm, du, ping, less) +Drop-in replacements for common Unix tools (\f[V]ls\f[R], \f[V]cat\f[R], +\f[V]rm\f[R], \f[V]du\f[R], \f[V]ping\f[R], \f[V]less\f[R]) .IP \[bu] 2 Deep Kitty and WezTerm terminal integration: tab/window/pane management from the command line .IP \[bu] 2 Optional session logging: terminal scrollback, tmux/zellij panes, and -paru/yay output captured to \[ti]/.terminal_history (off by default; see -below) +paru/yay output captured to \f[V]\[ti]/.terminal_history\f[R] (off by +default; see C5 Logging) .IP \[bu] 2 Automatic Python virtualenv activation on directory change .IP \[bu] 2 @@ -67,24 +68,6 @@ AI scaffolding helpers for Claude Code and Antigravity .IP \[bu] 2 Catppuccin Mocha color theme throughout .PP -CAUTION: \f[B]SESSION LOGGING\f[R] -.PD 0 -.P -.PD -If enabled, this configuration can silently record terminal output to -\f[V]\[ti]/.terminal_history\f[R]: Kitty scrollback on window close, -live tmux pane streams, zellij pane snapshots on exit, and full paru/yay -output. -These logs can contain command output, file contents, and secrets -printed to the terminal. -Nothing leaves your machine, but the files persist locally. -Logging is off unless you turn it on. -- Enable all logging with: \f[V]set -U __fish_config_op_logging on\f[R] -- Prefer a menu? -Run the interactive picker: \f[V]config-settings\f[R] - Turn it back off -with: \f[V]set -U __fish_config_op_logging off\f[R] (or erase the -variable) - See C5 \[em] Logging and Capture for the full breakdown. -.PP The configuration uses a structured file tree: .IP .nf @@ -222,7 +205,7 @@ T} .TE .PP Tools that respect XDG are directed to these paths rather than polluting -$HOME. +\f[V]$HOME\f[R]. .SS Tool Homes (XDG-compliant) .PP .TS @@ -685,7 +668,7 @@ gitig / git-ignore gi (generate .gitignore) .PP These abbreviations control the terminal emulator. Each has a Kitty variant and a WezTerm variant; the correct one is -inserted based on $TERM or $TERM_PROGRAM. +inserted based on \f[V]$TERM\f[R] or \f[V]$TERM_PROGRAM\f[R]. .IP .nf \f[C] @@ -3502,7 +3485,7 @@ Do not commit fish_variables. .PP Every opinionated piece of this config is active by default but can be switched off through six category opt-out variables, each evaluated via -__fish_variable_check. +\f[V]__fish_variable_check\f[R]. Set a variable to any falsy value (0, false, no, off, n) to disable its category; erase it or set a truthy value (1, true, yes, on, y) to re-enable. @@ -3510,7 +3493,7 @@ Unset means enabled \[em] except for C5 logging, which is opt-in (see below). .PP An explicit per-category truthy value takes precedence over the master -switch: setting __fish_config_opinionated=0 disables all unset +switch: setting \f[V]__fish_config_opinionated\f[R]=0 disables all unset categories, but a category with an explicit truthy value remains enabled regardless. .PP @@ -3683,7 +3666,7 @@ fish_config theme save \[dq]Catppuccin Latte\[dq] \f[R] .fi .PP - * * * * * +\f[V]---\f[R] .SH 8. COMPONENTS REFERENCE .PP The following tables detail every component in each category. @@ -3691,8 +3674,8 @@ Use this reference to understand exactly which behaviors change when you toggle a category variable. .SS C1 \[em] Command Shadows .PP -Disabling __fish_config_op_aliases restores standard system behavior for -all of these commands. +Disabling \f[V]__fish_config_op_aliases\f[R] restores standard system +behavior for all of these commands. .IP .nf \f[C] @@ -3727,7 +3710,7 @@ There is no intermediate safety net. .SS C2 \[em] Startup Side-Effects .PP These run automatically without any user action. -Disabling __fish_config_op_autoexec prevents all of them. +Disabling \f[V]__fish_config_op_autoexec\f[R] prevents all of them. .IP .nf \f[C] @@ -3753,16 +3736,17 @@ user-dots convenience symlink is not created. The symlink is git-ignored and only ever managed as a symlink \[em] a real file or directory at that path is left untouched. The symlink has its own opt-out independent of C2: set -__fish_user_dots_symlink to a falsy value (or toggle \[lq]Dots link\[rq] -off on the config-settings Paths page) to stop generating it and remove -any existing link \[em] honoured even when C2 is enabled. -Managed by the __fish_user_dots_link helper. -The first-run completion marker (__fish_config_first_run_complete) is -still set so the init does not re-run on subsequent shells. +\f[V]__fish_user_dots_symlink\f[R] to a falsy value (or toggle \[lq]Dots +link\[rq] off on the config-settings Paths page) to stop generating it +and remove any existing link \[em] honoured even when C2 is enabled. +Managed by the \f[V]__fish_user_dots_link\f[R] helper. +The first-run completion marker +(\f[V]__fish_config_first_run_complete\f[R]) is still set so the init +does not re-run on subsequent shells. .PP Python venv activation fires on every directory change. -If a directory uses direnv (.envrc present), direnv takes priority and -auto-venv is skipped for that directory. +If a directory uses direnv (\f[V].envrc\f[R] present), direnv takes +priority and auto-venv is skipped for that directory. .PP Auto-pull fast-forwards opted-in repositories in the background when you cd into them. @@ -3771,7 +3755,8 @@ The fish-config repo is always covered; other repos are added with the It only ever fast-forwards a clean repo whose branch has an upstream \[em] never rebases, merges, or overwrites work \[em] so it is a no-op on dirty trees, divergent branches, or repos without a remote. -The handler fires once per repo entry (not on every sub-directory cd). +The handler fires once per repo entry (not on every sub-directory +\f[V]cd\f[R]). 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 @@ -3780,7 +3765,7 @@ committed. .PP These change fundamental shell behavior: how keys work, which pager opens, and what the prompt looks like. -Disabling __fish_config_op_overrides removes all of them. +Disabling \f[V]__fish_config_op_overrides\f[R] removes all of them. .IP .nf \f[C] @@ -3805,8 +3790,9 @@ Right prompt fish_right_prompt: exit code (on failure) + dim timest \f[R] .fi .PP -The bang-bang system spans key_bindings.fish, abbr.fish, puffer.fish, -and six expand_bang_*.fish functions. +The bang-bang system spans \f[V]key_bindings.fish\f[R], +\f[V]abbr.fish\f[R], \f[V]puffer.fish\f[R], and six +\f[V]expand_bang_*.fish\f[R] functions. All are gated together \[em] disabling C3 removes the entire bang-expansion system at once. .PP @@ -3817,13 +3803,13 @@ below). .SS C4 \[em] Terminal and Tool Integration .PP These features couple the shell to specific external tools. -Disabling __fish_config_op_integrations disables all of them. +Disabling \f[V]__fish_config_op_integrations\f[R] disables all of them. .IP .nf \f[C] Component Requires ─────────────────────────────────────────────────────────────────────────── -\[ti]60 Kitty/WezTerm abbrs Active Kitty or WezTerm session +≈ 60 Kitty/WezTerm abbrs Active Kitty or WezTerm session (:w, :wv, :wh, :t, etc.) Done desktop notifications Graphical desktop with a notification daemon spwin Kitty or WezTerm @@ -3836,17 +3822,23 @@ WakaTime hook wakatime CLI and a configured API key \f[R] .fi .PP -Disabled integration commands (spwin, tab, split, hist, logs, upgrade) +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 C5 \[em] Logging and Capture .PP Five components capture shell output to disk. Unlike every other category, C5 is opt-in: it stays off until -__fish_config_op_logging is set to an explicit truthy value, and a -truthy master switch does not enable it. +\f[V]__fish_config_op_logging\f[R] is set to an explicit truthy value, +and a truthy master switch does not enable it. While it is off, all capture is skipped and the logging wrappers are removed. +.PP +CAUTION: This configuration is capable of silently recording terminal +output and secrets directly to disk. +See below for details on how this capture mechanism works, where files +are stored, and how to manage its state. .IP .nf \f[C] @@ -3859,16 +3851,16 @@ set -U __fish_config_op_logging off # or: set -Ue __fish_config_op_logging Component What it captures ─────────────────────────────────────────────────────────────────────────── Scrollback capture Terminal session output saved to: - \[ti]/.terminal_history/scrollback_YYYY-MM-DD_HH-MM-SS.log + \[ga]\[ti]/.terminal_history/scrollback_YYYY-MM-DD_HH-MM-SS.log\[ga] tmux pane capture Continuous pane stream via pipe-pane, saved to: - \[ti]/.terminal_history/tmux_-w-p_YYYY-MM-DD_HH-MM-SS.log + \[ga]\[ti]/.terminal_history/tmux_-w-p_YYYY-MM-DD_HH-MM-SS.log\[ga] zellij pane capture Pane scrollback snapshot on shell exit, saved to: - \[ti]/.terminal_history/zellij_-p_YYYY-MM-DD_HH-MM-SS.log + \[ga]\[ti]/.terminal_history/zellij_-p_YYYY-MM-DD_HH-MM-SS.log\[ga] paru wrapper All paru/AUR output captured to: - \[ti]/.terminal_history/paru_YYYY-MM-DD_HH-MM-SS.log + \[ga]\[ti]/.terminal_history/paru_YYYY-MM-DD_HH-MM-SS.log\[ga] yay wrapper All yay/AUR output captured to: - \[ti]/.terminal_history/yay_YYYY-MM-DD_HH-MM-SS.log -Kitty watcher watcher.py captures scrollback when Kitty closes + \[ga]\[ti]/.terminal_history/yay_YYYY-MM-DD_HH-MM-SS.log\[ga] +Kitty watcher \[ga]watcher.py\[ga] captures scrollback when Kitty closes \f[R] .fi .PP @@ -3880,29 +3872,31 @@ They remain in \f[V]$SCROLLBACK_HISTORY_DIR\f[R] (defaults to: \f[V]\[ti]/.terminal_history/\f[R]) until you remove them manually. .PP The tmux capture starts automatically when fish launches inside any tmux -pane ($TMUX is set). +pane (\f[V]$TMUX\f[R] is set). It uses tmux\[cq]s native pipe-pane to stream all pane output directly to disk without an intermediate process. Each fish shell session gets its own log file; a new log is created on each shell start (including exec fish and new splits). -Before each new log, the oldest tmux_*.log files are pruned (by -modification time) to keep the total within -SCROLLBACK_HISTORY_MAX_FILES, matching the paru/yay wrapper behaviour. +Before each new log, the oldest \f[V]tmux_*.log\f[R] files are pruned +(by modification time) to keep the total within +\f[V]SCROLLBACK_HISTORY_MAX_FILES\f[R], matching the paru/yay wrapper +behaviour. .PP The zellij capture works differently: Zellij has no live output-streaming facility like pipe-pane, so the log is taken as a one-shot snapshot when the shell exits, via -\f[V]zellij action dump-screen --full --ansi\f[R] (the \[en]ansi flag -preserves color). +\f[V]zellij action dump-screen --full --ansi\f[R] (the \f[V]--ansi\f[R] +flag preserves color). The dump is captured on the fish process\[cq]s stdout and written to the log file by fish itself (not via \f[V]--path\f[R], which would make the zellij server write the file). -A fish_exit handler (registered whenever $ZELLIJ is set) writes the -pane\[cq]s full scrollback and then prunes old zellij_*.log files the -same way. -Because the capture happens at exit, toggling __fish_config_op_logging -takes effect on the next exit with no restart or sentinel coordination -needed \[em] the C5 guard is re-checked when the handler fires. +A fish_exit handler (registered whenever \f[V]$ZELLIJ\f[R] is set) +writes the pane\[cq]s full scrollback and then prunes old +\f[V]zellij_*.log\f[R] files the same way. +Because the capture happens at exit, toggling +\f[V]__fish_config_op_logging\f[R] takes effect on the next exit with no +restart or sentinel coordination needed \[em] the C5 guard is re-checked +when the handler fires. .PP LIMITATION \[em] zellij capture only fires on a clean shell exit (typing \f[V]exit\f[R], Ctrl-D, or a logout), because that is when the fish_exit @@ -3927,14 +3921,14 @@ To guarantee a zellij pane is logged, end the session with actions. .PP The Kitty watcher is managed by the kitty-logging command: it symlinks -the watcher (fish-config-watcher.py) into the Kitty config directory and -wires it into kitty.conf via a managed block. +the watcher (\f[V]fish-config-watcher.py\f[R]) into the Kitty config +directory and wires it into \f[V]kitty.conf\f[R] via a managed block. Inside Kitty, a non-blocking per-session reminder points first-time users at \f[V]kitty-logging install\f[R] until they install or run \f[V]kitty-logging dismiss\f[R]; the reminder is itself gated on C5, so it stays silent until you enable logging. Install affects new Kitty windows only; runtime disable is still handled -by the .logging_disabled sentinel. +by the \f[V].logging_disabled\f[R] sentinel. .PP Logging coordination via sentinel file .PP @@ -3948,34 +3942,37 @@ out-of-process components (the Kitty watcher and all running shells): .fi .PP Because C5 is off by default, the sentinel is present on a fresh install -\[em] the startup sync in conf.d/logging-events.fish reconciles it on -every shell start, so it appears without any action on your part. +\[em] the startup sync in \f[V]conf.d/logging-events.fish\f[R] +reconciles it on every shell start, so it appears without any action on +your part. .PP -Disabling __fish_config_op_logging (or leaving it unset): 1. +Disabling \f[V]__fish_config_op_logging\f[R] (or leaving it unset): 1. Creates the sentinel immediately in every open shell. 2. -Removes \[ti]/.local/bin/paru and \[ti]/.local/bin/yay logging wrappers; -bare /usr/bin/paru and /usr/bin/yay are used instead. +Removes \f[V]\[ti]/.local/bin/paru\f[R] and +\f[V]\[ti]/.local/bin/yay\f[R] logging wrappers; bare +\f[V]/usr/bin/paru\f[R] and \f[V]/usr/bin/yay\f[R] are used instead. 3. -Kitty\[cq]s watcher.py reads the sentinel on each save attempt and skips -capture \[em] no Kitty restart required. +Kitty\[cq]s \f[V]watcher.py\f[R] reads the sentinel on each save attempt +and skips capture \[em] no Kitty restart required. 4. smart_exit stops saving scrollback logs. 5. -Stops tmux pipe-pane capture in every open fish shell inside tmux. +Stops \f[V]tmux pipe-pane\f[R] capture in every open fish shell inside +tmux. .PP -Enabling __fish_config_op_logging: 1. +Enabling \f[V]__fish_config_op_logging\f[R]: 1. Removes the sentinel in every open shell. 2. -Regenerates paru/yay logging wrappers in \[ti]/.local/bin/. +Regenerates paru/yay logging wrappers in \f[V]\[ti]/.local/bin/\f[R]. 3. Kitty watcher resumes capture on the next session exit. 4. Restarts tmux pipe-pane capture in every open fish shell inside tmux. .PP Changes propagate to all running shells through an event handler that -fires whenever __fish_config_op_logging changes \[em] no shell restart -needed. +fires whenever \f[V]__fish_config_op_logging\f[R] changes \[em] no shell +restart needed. .PP Note: C3 and C5 compose independently. C3 controls whether the smart_exit wrapper is active at all; C5 controls @@ -4002,8 +3999,8 @@ config simply does not override it. Fisher is bootstrapped automatically on the \f[B]first interactive session\f[R] via \f[V]conf.d/first_run.fish\f[R]. This also applies the Catppuccin Mocha theme and prints a one-time -welcome message (gated by __fish_config_op_greeting; set it to 0 to -suppress). +welcome message (gated by \f[V]__fish_config_op_greeting\f[R]; set it to +0 to suppress). Subsequent sessions skip all first-run logic with zero overhead. .PP To re-trigger first-run initialization (e.g., after a fresh install or @@ -4546,12 +4543,12 @@ that only manages basic features like \f[V]XDG\f[R] variables, and your \f[C] Category Description ────────────────────────────────────────────────────────────────────────── -C1 Command Shadows (aliases that replace default tools) -C2 Auto-Exec (background tasks and startup side-effects) -C3 Key & Env Overrides (Vi mode, PAGER) -C4 Terminal Integrations (Kitty, WezTerm) -C5 Logging and Capture (session logs, command duration) -C6 Greeting & First-Run UI (custom startup banner) +C1 | Command Shadows | Wraps destructive commands (\[ga]rm\[ga], \[ga]cp\[ga]) to be safe by default | +C2 | Startup Side-Effects | Bootstraps Fisher, generates wrappers, auto-activates venvs | +C3 | Overrides | Overrides \[ga]cd\[ga], sets Vi mode, binds \[ga]\[ga] to \[ga]smart_enter\[ga] | +C4 | Integrations | Kitty/Wezterm integrations, starship hooks, fzf theme | +C5 | Logging and Capture | Session logs, command duration | +C6 | Greeting & First-Run UI | Custom startup banner | \f[R] .fi .PP