From 78f957b211f5d3aaa6362f9b082c39d808a44ac8 Mon Sep 17 00:00:00 2001 From: Gitea Actions Date: Mon, 27 Jul 2026 04:59:58 +0000 Subject: [PATCH] chore(docs): regenerate manual and man page --- docs/fish-config.1 | 700 ++++++++++++++++++++++++++++++++------------- 1 file changed, 507 insertions(+), 193 deletions(-) diff --git a/docs/fish-config.1 b/docs/fish-config.1 index 0bf3687..076fb3e 100644 --- a/docs/fish-config.1 +++ b/docs/fish-config.1 @@ -1,3 +1,4 @@ +'\" t .\" Automatically generated by Pandoc 3.1.3 .\" .\" Define V font for inline verbatim, using C font in formats @@ -182,172 +183,325 @@ These variables are exported from config.fish on every interactive session. Override them in local.fish (see Section 10, Personalization). .SS Environment Directories (XDG) -.IP -.nf -\f[C] -XDG_CONFIG_HOME \[ti]/.config -XDG_CACHE_HOME \[ti]/.cache -XDG_DATA_HOME \[ti]/.local/share -XDG_STATE_HOME \[ti]/.local/state -\f[R] -.fi +.PP +.TS +tab(@); +l l. +T{ +Variable +T}@T{ +Value +T} +_ +T{ +\f[V]XDG_CONFIG_HOME\f[R] +T}@T{ +\f[V]\[ti]/.config\f[R] +T} +T{ +\f[V]XDG_CACHE_HOME\f[R] +T}@T{ +\f[V]\[ti]/.cache\f[R] +T} +T{ +\f[V]XDG_DATA_HOME\f[R] +T}@T{ +\f[V]\[ti]/.local/share\f[R] +T} +T{ +\f[V]XDG_STATE_HOME\f[R] +T}@T{ +\f[V]\[ti]/.local/state\f[R] +T} +.TE .PP Tools that respect XDG are directed to these paths rather than polluting $HOME. .SS Tool Homes (XDG-compliant) -.IP -.nf -\f[C] -CARGO_HOME $XDG_DATA_HOME/cargo -RUSTUP_HOME $XDG_DATA_HOME/rustup -GOPATH $XDG_DATA_HOME/go -BUN_INSTALL $XDG_DATA_HOME/bun -NPM_CONFIG_PREFIX $XDG_DATA_HOME/npm-global -GNUPGHOME $XDG_CONFIG_HOME/gnupg -WAKATIME_HOME $XDG_CONFIG_HOME/wakatime -\f[R] -.fi +.PP +.TS +tab(@); +l l. +T{ +Variable +T}@T{ +Value +T} +_ +T{ +\f[V]CARGO_HOME\f[R] +T}@T{ +\f[V]$XDG_DATA_HOME/cargo\f[R] +T} +T{ +\f[V]RUSTUP_HOME\f[R] +T}@T{ +\f[V]$XDG_DATA_HOME/rustup\f[R] +T} +T{ +\f[V]GOPATH\f[R] +T}@T{ +\f[V]$XDG_DATA_HOME/go\f[R] +T} +T{ +\f[V]BUN_INSTALL\f[R] +T}@T{ +\f[V]$XDG_DATA_HOME/bun\f[R] +T} +T{ +\f[V]NPM_CONFIG_PREFIX\f[R] +T}@T{ +\f[V]$XDG_DATA_HOME/npm-global\f[R] +T} +T{ +\f[V]GNUPGHOME\f[R] +T}@T{ +\f[V]$XDG_CONFIG_HOME/gnupg\f[R] +T} +T{ +\f[V]WAKATIME_HOME\f[R] +T}@T{ +\f[V]$XDG_CONFIG_HOME/wakatime\f[R] +T} +.TE .SS Editor and Pager -.IP -.nf -\f[C] -EDITOR nvim (falls back to vi if nvim is absent) -VISUAL unset by default; set a GUI editor via local.fish (the edit - function falls back to a GUI chain when VISUAL is empty) -SUDO_EDITOR same as EDITOR -PAGER ov (falls back to less) -\f[R] -.fi +.PP +.TS +tab(@); +lw(35.0n) lw(35.0n). +T{ +Variable +T}@T{ +Value / Notes +T} +_ +T{ +\f[V]EDITOR\f[R] +T}@T{ +\f[V]nvim\f[R] (falls back to \f[V]vi\f[R] if \f[V]nvim\f[R] is absent) +T} +T{ +\f[V]VISUAL\f[R] +T}@T{ +unset by default; set a GUI editor via \f[V]local.fish\f[R] (the +\f[V]edit\f[R] function falls back to a GUI chain when \f[V]VISUAL\f[R] +is empty) +T} +T{ +\f[V]SUDO_EDITOR\f[R] +T}@T{ +same as \f[V]EDITOR\f[R] +T} +T{ +\f[V]PAGER\f[R] +T}@T{ +\f[V]ov\f[R] (falls back to \f[V]less\f[R]) +T} +.TE .SS Scrollback History -.IP -.nf -\f[C] -__fish_scrollback_history_dir (unset → \[ti]/.terminal_history) -__fish_scrollback_history_max_files (unset → 100) -SCROLLBACK_HISTORY_DIR \[ti]/.terminal_history (exported mirror) -SCROLLBACK_HISTORY_MAX_FILES 100 (exported mirror) -\f[R] -.fi .PP -The __fish_scrollback_history_* universal variables are the fish-style -source of truth \[em] set them via \f[V]config-settings\f[R] → Paths, or -\f[V]set -U\f[R] directly. -config.fish exports the SCROLLBACK_HISTORY_* mirrors from them, because -the POSIX wrapper scripts (paru/yay/tmux/zellij logging and -_prune_terminal_logs) read the exported names from the environment. -When the __fish_ vars are unset, the documented defaults are exported. -config.fish deliberately does not create a global source var, which -would shadow the universal and stop live edits from taking effect. +.TS +tab(@); +l l. +T{ +Variable +T}@T{ +Value / Notes +T} +_ +T{ +\f[V]__fish_scrollback_history_dir\f[R] +T}@T{ +(unset → \f[V]\[ti]/.terminal_history\f[R]) +T} +T{ +\f[V]__fish_scrollback_history_max_files\f[R] +T}@T{ +(unset → \f[V]100\f[R]) +T} +T{ +\f[V]SCROLLBACK_HISTORY_DIR\f[R] +T}@T{ +\f[V]\[ti]/.terminal_history\f[R] (exported mirror) +T} +T{ +\f[V]SCROLLBACK_HISTORY_MAX_FILES\f[R] +T}@T{ +\f[V]100\f[R] (exported mirror) +T} +.TE .PP -Scrollback logs accumulate in SCROLLBACK_HISTORY_DIR as timestamped -files. -When the count exceeds SCROLLBACK_HISTORY_MAX_FILES the oldest are -pruned automatically on exit. +The \f[V]__fish_scrollback_history_*\f[R] universal variables are the +fish-style source of truth \[em] set them via \f[V]config-settings\f[R] +→ Paths, or \f[V]set -U\f[R] directly. +\f[V]config.fish\f[R] exports the \f[V]SCROLLBACK_HISTORY_*\f[R] mirrors +from them, because the POSIX wrapper scripts +(\f[V]paru\f[R]/\f[V]yay\f[R]/\f[V]tmux\f[R]/\f[V]zellij\f[R] logging +and \f[V]_prune_terminal_logs\f[R]) read the exported names from the +environment. +When the \f[V]__fish_\f[R] vars are unset, the documented defaults are +exported. +\f[V]config.fish\f[R] deliberately does not create a global source var, +which would shadow the universal and stop live edits from taking effect. +.PP +Scrollback logs accumulate in \f[V]SCROLLBACK_HISTORY_DIR\f[R] as +timestamped files. +When the count exceeds \f[V]SCROLLBACK_HISTORY_MAX_FILES\f[R] the oldest +are pruned automatically on exit. Use \f[V]logs\f[R] to browse them interactively. .SS Other -.IP -.nf -\f[C] -GPG_TTY $(tty) \[em] ensures GPG passphrase prompts work -CLAUDE_CODE_NO_FLICKER 1 \[em] suppress terminal flicker in Claude Code -CDPATH . \[ti]/projects \[ti] -\f[R] -.fi .PP -Opinionated defaults (CDPATH, PAGER/MANPAGER, Vi mode, command shadows, -terminal integrations) can be switched off per category with universal -variables \[em] see Section 7, \[lq]Opinionated Components (Minimal -Mode)\[rq]. +.TS +tab(@); +lw(23.3n) lw(23.3n) lw(23.3n). +T{ +Variable +T}@T{ +Value +T}@T{ +Notes +T} +_ +T{ +\f[V]GPG_TTY\f[R] +T}@T{ +\f[V]$(tty)\f[R] +T}@T{ +ensures GPG passphrase prompts work +T} +T{ +\f[V]CLAUDE_CODE_NO_FLICKER\f[R] +T}@T{ +\f[V]1\f[R] +T}@T{ +suppress terminal flicker in Claude Code +T} +T{ +\f[V]CDPATH\f[R] +T}@T{ +\f[V]. \[ti]/projects \[ti]\f[R] +T}@T{ +T} +.TE +.PP +Opinionated defaults (\f[V]CDPATH\f[R], +\f[V]PAGER\f[R]/\f[V]MANPAGER\f[R], Vi mode, command shadows, terminal +integrations) can be switched off per category with universal variables +\[em] see Section 7, \[lq]Opinionated Components (Minimal Mode)\[rq]. .SS Pager Hierarchy .PP -$PAGER is set to ov when available, falling back to less. -The less wrapper function extends this into a full chain so anything -that calls less directly also benefits: -.IP -.nf -\f[C] -$PAGER → ov → less → more → cat -\f[R] -.fi +\f[V]$PAGER\f[R] is set to \f[V]ov\f[R] when available, falling back to +\f[V]less\f[R]. +The \f[V]less\f[R] wrapper function extends this into a full chain so +anything that calls \f[V]less\f[R] directly also benefits: .PP -When bat is installed, man pages are rendered with syntax highlighting: -.IP -.nf -\f[C] -MANROFFOPT -c -MANPAGER sh -c \[aq]col -bx | bat -l man -p\[aq] -\f[R] -.fi +\f[V]$PAGER\f[R] → \f[V]ov\f[R] → \f[V]less\f[R] → \f[V]more\f[R] → +\f[V]cat\f[R] +.PP +When \f[V]bat\f[R] is installed, man pages are rendered with syntax +highlighting: +.PP +.TS +tab(@); +l l. +T{ +Variable +T}@T{ +Value +T} +_ +T{ +\f[V]MANROFFOPT\f[R] +T}@T{ +\f[V]-c\f[R] +T} +T{ +\f[V]MANPAGER\f[R] +T}@T{ +\f[V]sh -c \[aq]col -bx \[rs]| bat -l man -p\[aq]\f[R] +T} +.TE .SS Integrations .SS Zoxide .PP -cd, z, and cdi/zi are all mapped to zoxide-backed navigation. -Tab completions for cd and z blend standard directory entries (CWD and -CDPATH) with frecency results so both familiar and frequently-visited -paths appear in one list. +\f[V]cd\f[R], \f[V]z\f[R], and \f[V]cdi\f[R]/\f[V]zi\f[R] are all mapped +to \f[V]zoxide\f[R]-backed navigation. +Tab completions for \f[V]cd\f[R] and \f[V]z\f[R] blend standard +directory entries (CWD and \f[V]CDPATH\f[R]) with frecency results so +both familiar and frequently-visited paths appear in one list. .SS DirEnv .PP -Automatically loads .envrc files on directory change. +Automatically loads \f[V].envrc\f[R] files on directory change. Takes priority over the auto-venv logic \[em] if a directory is managed -by direnv, the auto-venv activation is skipped entirely. +by \f[V]direnv\f[R], the auto-venv activation is skipped entirely. .SS Auto Python Venv .PP -When entering a directory that contains a .venv/, the virtualenv is -activated automatically and deactivated when you leave the project tree. +When entering a directory that contains a \f[V].venv/\f[R], the +virtualenv is activated automatically and deactivated when you leave the +project tree. .SS WakaTime .PP Every shell command is reported to WakaTime for time-tracking. -Set FISH_WAKATIME_DISABLED=1 to disable without removing the plugin. +Set \f[V]FISH_WAKATIME_DISABLED=1\f[R] to disable without removing the +plugin. .SS Tailscale .PP -Full tab completion for the tailscale CLI is provided via -conf.d/tailscale.fish. +Full tab completion for the \f[V]tailscale\f[R] CLI is provided via +\f[V]conf.d/tailscale.fish\f[R]. .SS Done Notifications .PP Desktop notifications fire when a command takes longer than 10 seconds and the terminal window is not focused. Configured via fish universal variables: -.IP -.nf -\f[C] -__done_min_cmd_duration 10000 ms -__done_notification_urgency_level low -\f[R] -.fi +.PP +.TS +tab(@); +l l. +T{ +Variable +T}@T{ +Value +T} +_ +T{ +\f[V]__done_min_cmd_duration\f[R] +T}@T{ +\f[V]10000\f[R] ms +T} +T{ +\f[V]__done_notification_urgency_level\f[R] +T}@T{ +\f[V]low\f[R] +T} +.TE .SS Scrollback History .PP -When running inside Kitty, closing a shell session via exit saves a -timestamped scrollback snapshot to SCROLLBACK_HISTORY_DIR. +When running inside Kitty, closing a shell session via \f[V]exit\f[R] +saves a timestamped scrollback snapshot to +\f[V]SCROLLBACK_HISTORY_DIR\f[R]. Files are named: -.IP -.nf -\f[C] -scrollback_YYYY-MM-DD_HH-MM-SS.log -\f[R] -.fi .PP -The paru and yay wrappers (auto-generated in \[ti]/.local/bin/) run the -command inside a PTY via script(1) so download progress bars are -preserved on screen, then render the captured terminal animation down to -a clean static log via scripts/clean_progress_log.py (a small -terminal-screen emulator that replays cursor movements, collapses -repainted progress frames to their final state, and preserves ANSI -color). -If python3 is unavailable the wrapper falls back to dropping only the -script(1) header/footer. +\f[V]scrollback_YYYY-MM-DD_HH-MM-SS.log\f[R] +.PP +The \f[V]paru\f[R] and \f[V]yay\f[R] wrappers (auto-generated in +\f[V]\[ti]/.local/bin/\f[R]) run the command inside a PTY via +\f[V]script(1)\f[R] so download progress bars are preserved on screen, +then render the captured terminal animation down to a clean static log +via \f[V]scripts/clean_progress_log.py\f[R] (a small terminal-screen +emulator that replays cursor movements, collapses repainted progress +frames to their final state, and preserves ANSI color). +If \f[V]python3\f[R] is unavailable the wrapper falls back to dropping +only the \f[V]script(1)\f[R] header/footer. Output is saved to: -.IP -.nf -\f[C] -paru_YYYY-MM-DD_HH-MM-SS.log -yay_YYYY-MM-DD_HH-MM-SS.log -\f[R] -.fi +.IP \[bu] 2 +\f[V]paru_YYYY-MM-DD_HH-MM-SS.log\f[R] +.IP \[bu] 2 +\f[V]yay_YYYY-MM-DD_HH-MM-SS.log\f[R] .PP -Before pruning, _scrollback_prune_junk silently removes empty files, -files with only a single meaningful line (e.g.\ bare [exited] captures), -and Kitty tab-rename prompt captures. -Use exit \[en]no-log (or exit -n) to skip capture. +Before pruning, \f[V]_scrollback_prune_junk\f[R] silently removes empty +files, files with only a single meaningful line (e.g.\ bare +\f[V][exited]\f[R] captures), and Kitty tab-rename prompt captures. +Use \f[V]exit --no-log\f[R] (or \f[V]exit -n\f[R]) to skip capture. .PP * * * * * .SH 2. PATH SETUP @@ -2846,79 +3000,236 @@ fish-deps manages these tools. Run \f[V]fish-deps\f[R] to check status, or \f[V]fish-deps install\f[R] to install missing ones. .SS Required -.IP -.nf -\f[C] -fish Fish shell >= 4.0 -fzf Fuzzy finder -zoxide Smart cd with frecency -\f[R] -.fi +.PP +.TS +tab(@); +l l. +T{ +Tool +T}@T{ +Description +T} +_ +T{ +\f[V]fish\f[R] +T}@T{ +Fish shell >= 4.0 +T} +T{ +\f[V]fzf\f[R] +T}@T{ +Fuzzy finder +T} +T{ +\f[V]zoxide\f[R] +T}@T{ +Smart cd with frecency +T} +.TE .SS Integrations -.IP -.nf -\f[C] -wakatime Developer time tracking -tailscale Mesh VPN client -\f[R] -.fi +.PP +.TS +tab(@); +l l. +T{ +Tool +T}@T{ +Description +T} +_ +T{ +\f[V]wakatime\f[R] +T}@T{ +Developer time tracking +T} +T{ +\f[V]tailscale\f[R] +T}@T{ +Mesh VPN client +T} +.TE .SS Recommended -.IP -.nf -\f[C] -cargo Rust toolchain (via rustup); used by fish-deps to install - Rust-based tools and to build fish from source. All paths - are gated on type -q cargo and degrade gracefully. -starship Cross-shell prompt; loaded via type -q starship guard. - Without it the Catppuccin nim-style fallback prompt activates. -uv Python package and project manager (Astral); used by the - fish-from-source build path in fish-deps. All consumers - degrade gracefully without it. -direnv Per-directory environment loading; integration is fully - guarded with type -q direnv. Without it the direnv hook - is simply not loaded and auto-venv activates normally. -paru AUR helper (Arch only; preferred); guarded throughout \[em] - non-Arch systems silently skip AUR-specific paths. -yay AUR helper (Arch only; fallback to paru); same guards apply. -eza Modern ls replacement -lsd ls replacement (fallback to eza) -bat Syntax-highlighted cat -btop Modern resource monitor -dust Disk usage tree (Rust) -duf Disk usage/free overview -prettyping Colorized ping wrapper -ov Modern pager (replaces less) -ripgrep Fast line search -lazygit Terminal git UI -lazydocker Terminal docker UI -trash Safe delete (trash-cli) -kitty GPU-accelerated terminal (primary) -wezterm GPU-accelerated terminal (alternative) -python3 Standalone interpreter \[em] used by the paru/yay log cleaner. - Note: uv does not provide python3 on PATH, and Arch\[aq]s base - does not include it, so it is listed separately. All - consumers degrade gracefully without it. -yt-dlp Video/media downloader; backs the yt-dlp wrapper function. - Optional \[em] the wrapper falls back to the system yt-dlp and - the rest of the config works without it. -\f[R] -.fi +.PP +.TS +tab(@); +lw(35.0n) lw(35.0n). +T{ +Tool +T}@T{ +Description +T} +_ +T{ +\f[V]cargo\f[R] +T}@T{ +Rust toolchain (via rustup); used by \f[V]fish-deps\f[R] to install +Rust-based tools and to build fish from source. +All paths are gated on \f[V]type -q cargo\f[R] and degrade gracefully. +T} +T{ +\f[V]starship\f[R] +T}@T{ +Cross-shell prompt; loaded via \f[V]type -q starship\f[R] guard. +Without it the Catppuccin nim-style fallback prompt activates. +T} +T{ +\f[V]uv\f[R] +T}@T{ +Python package and project manager (Astral); used by the +fish-from-source build path in \f[V]fish-deps\f[R]. +All consumers degrade gracefully without it. +T} +T{ +\f[V]direnv\f[R] +T}@T{ +Per-directory environment loading; integration is fully guarded with +\f[V]type -q direnv\f[R]. +Without it the direnv hook is simply not loaded and auto-venv activates +normally. +T} +T{ +\f[V]paru\f[R] +T}@T{ +AUR helper (Arch only; preferred); guarded throughout \[em] non-Arch +systems silently skip AUR-specific paths. +T} +T{ +\f[V]yay\f[R] +T}@T{ +AUR helper (Arch only; fallback to paru); same guards apply. +T} +T{ +\f[V]eza\f[R] +T}@T{ +Modern \f[V]ls\f[R] replacement +T} +T{ +\f[V]lsd\f[R] +T}@T{ +\f[V]ls\f[R] replacement (fallback to \f[V]eza\f[R]) +T} +T{ +\f[V]bat\f[R] +T}@T{ +Syntax-highlighted \f[V]cat\f[R] +T} +T{ +\f[V]btop\f[R] +T}@T{ +Modern resource monitor +T} +T{ +\f[V]dust\f[R] +T}@T{ +Disk usage tree (Rust) +T} +T{ +\f[V]duf\f[R] +T}@T{ +Disk usage/free overview +T} +T{ +\f[V]prettyping\f[R] +T}@T{ +Colorized ping wrapper +T} +T{ +\f[V]ov\f[R] +T}@T{ +Modern pager (replaces \f[V]less\f[R]) +T} +T{ +\f[V]ripgrep\f[R] +T}@T{ +Fast line search +T} +T{ +\f[V]lazygit\f[R] +T}@T{ +Terminal git UI +T} +T{ +\f[V]lazydocker\f[R] +T}@T{ +Terminal docker UI +T} +T{ +\f[V]trash\f[R] +T}@T{ +Safe delete (\f[V]trash-cli\f[R]) +T} +T{ +\f[V]kitty\f[R] +T}@T{ +GPU-accelerated terminal (primary) +T} +T{ +\f[V]wezterm\f[R] +T}@T{ +GPU-accelerated terminal (alternative) +T} +T{ +\f[V]python3\f[R] +T}@T{ +Standalone interpreter \[em] used by the \f[V]paru\f[R]/\f[V]yay\f[R] +log cleaner. +Note: \f[V]uv\f[R] does not provide \f[V]python3\f[R] on PATH, and +Arch\[cq]s base does not include it, so it is listed separately. +All consumers degrade gracefully without it. +T} +T{ +\f[V]yt-dlp\f[R] +T}@T{ +Video/media downloader; backs the \f[V]yt-dlp\f[R] wrapper function. +Optional \[em] the wrapper falls back to the system \f[V]yt-dlp\f[R] and +the rest of the config works without it. +T} +.TE .SS Install Methods .PP The install priority for each tool: -.IP -.nf -\f[C] -cargo Rust tools (eza, lsd, bat, dust, ov, ripgrep, trashy, zoxide, - starship) \[em] always gets the latest crate version -system PM paru / apt / brew / dnf / etc. \[em] for tools without a crate -git clone fzf \[em] installed from GitHub to \[ti]/.fzf/ -curl starship installer, fisher bootstrap, uv installer -\f[R] -.fi +.PP +.TS +tab(@); +lw(35.0n) lw(35.0n). +T{ +Method +T}@T{ +Packages +T} +_ +T{ +\f[V]cargo\f[R] +T}@T{ +Rust tools (\f[V]eza\f[R], \f[V]lsd\f[R], \f[V]bat\f[R], \f[V]dust\f[R], +\f[V]ov\f[R], \f[V]ripgrep\f[R], \f[V]trashy\f[R], \f[V]zoxide\f[R], +\f[V]starship\f[R]) \[em] always gets the latest crate version +T} +T{ +system PM +T}@T{ +\f[V]paru\f[R] / \f[V]apt\f[R] / \f[V]brew\f[R] / \f[V]dnf\f[R] / etc. +\[em] for tools without a crate +T} +T{ +\f[V]git clone\f[R] +T}@T{ +\f[V]fzf\f[R] \[em] installed from GitHub to \f[V]\[ti]/.fzf/\f[R] +T} +T{ +\f[V]curl\f[R] +T}@T{ +\f[V]starship\f[R] installer, \f[V]fisher\f[R] bootstrap, \f[V]uv\f[R] +installer +T} +.TE .PP * * * * * .SH 7. CUSTOMIZATION +.PP +This section explains how to adapt the configuration to your specific +workflow, including local machine overrides and opinionated component +toggles. .SS Machine-local Configuration .PP Place machine-specific settings that should not be committed to git in: @@ -3704,6 +4015,9 @@ local.fish in turn sources secrets.fish when it exists. .PP * * * * * .SH 11. TROUBLESHOOTING +.PP +This section covers common issues, their solutions, and how to safely +revert changes or uninstall the configuration entirely. .SS Uninstalling / Reverting to Backup .PP The installation step backs up any existing config to