diff --git a/docs/fish-config.md b/docs/fish-config.md index ad7073e..85b7028 100644 --- a/docs/fish-config.md +++ b/docs/fish-config.md @@ -148,131 +148,144 @@ Override them in local.fish (see Section 10, Personalization). ## Environment Directories (XDG) - XDG_CONFIG_HOME ~/.config - XDG_CACHE_HOME ~/.cache - XDG_DATA_HOME ~/.local/share - XDG_STATE_HOME ~/.local/state +| Variable | Value | +|---|---| +| `XDG_CONFIG_HOME` | `~/.config` | +| `XDG_CACHE_HOME` | `~/.cache` | +| `XDG_DATA_HOME` | `~/.local/share` | +| `XDG_STATE_HOME` | `~/.local/state` | Tools that respect XDG are directed to these paths rather than polluting $HOME. ## Tool Homes (XDG-compliant) - 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 +| Variable | Value | +|---|---| +| `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` | ## Editor and Pager - 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) +| Variable | Value / Notes | +|---|---| +| `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`) | ## Scrollback History - __fish_scrollback_history_dir (unset → ~/.terminal_history) - __fish_scrollback_history_max_files (unset → 100) - SCROLLBACK_HISTORY_DIR ~/.terminal_history (exported mirror) - SCROLLBACK_HISTORY_MAX_FILES 100 (exported mirror) +| Variable | Value / Notes | +|---|---| +| `__fish_scrollback_history_dir` | (unset → `~/.terminal_history`) | +| `__fish_scrollback_history_max_files` | (unset → `100`) | +| `SCROLLBACK_HISTORY_DIR` | `~/.terminal_history` (exported mirror) | +| `SCROLLBACK_HISTORY_MAX_FILES` | `100` (exported mirror) | -The __fish_scrollback_history_* universal variables are the fish-style source +The `__fish_scrollback_history_*` universal variables are the fish-style source of truth — set them via `config-settings` → Paths, or `set -U` 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 +`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. -Scrollback logs accumulate in SCROLLBACK_HISTORY_DIR as timestamped files. -When the count exceeds SCROLLBACK_HISTORY_MAX_FILES the oldest are pruned +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. Use `logs` to browse them interactively. ## Other - GPG_TTY $(tty) — ensures GPG passphrase prompts work - CLAUDE_CODE_NO_FLICKER 1 — suppress terminal flicker in Claude Code - CDPATH . ~/projects ~ +| Variable | Value | Notes | +|---|---|---| +| `GPG_TTY` | `$(tty)` | ensures GPG passphrase prompts work | +| `CLAUDE_CODE_NO_FLICKER` | `1` | suppress terminal flicker in Claude Code | +| `CDPATH` | `. ~/projects ~` | | -Opinionated defaults (CDPATH, PAGER/MANPAGER, Vi mode, command shadows, +Opinionated defaults (`CDPATH`, `PAGER`/`MANPAGER`, Vi mode, command shadows, terminal integrations) can be switched off per category with universal variables — see Section 7, "Opinionated Components (Minimal Mode)". ## Pager Hierarchy -$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 +`$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: - $PAGER → ov → less → more → cat +`$PAGER` → `ov` → `less` → `more` → `cat` -When bat is installed, man pages are rendered with syntax highlighting: +When `bat` is installed, man pages are rendered with syntax highlighting: - MANROFFOPT -c - MANPAGER sh -c 'col -bx | bat -l man -p' +| Variable | Value | +|---|---| +| `MANROFFOPT` | `-c` | +| `MANPAGER` | `sh -c 'col -bx \| bat -l man -p'` | ## Integrations ### Zoxide -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 +`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. ### DirEnv -Automatically loads .envrc files on directory change. Takes priority over -the auto-venv logic — if a directory is managed by direnv, the auto-venv +Automatically loads `.envrc` files on directory change. Takes priority over +the auto-venv logic — if a directory is managed by `direnv`, the auto-venv activation is skipped entirely. ### Auto Python Venv -When entering a directory that contains a .venv/, the virtualenv is activated +When entering a directory that contains a `.venv/`, the virtualenv is activated automatically and deactivated when you leave the project tree. ### WakaTime Every shell command is reported to WakaTime for time-tracking. Set -FISH_WAKATIME_DISABLED=1 to disable without removing the plugin. +`FISH_WAKATIME_DISABLED=1` to disable without removing the plugin. ### Tailscale -Full tab completion for the tailscale CLI is provided via conf.d/tailscale.fish. +Full tab completion for the `tailscale` CLI is provided via `conf.d/tailscale.fish`. ### Done Notifications Desktop notifications fire when a command takes longer than 10 seconds and the terminal window is not focused. Configured via fish universal variables: - __done_min_cmd_duration 10000 ms - __done_notification_urgency_level low +| Variable | Value | +|---|---| +| `__done_min_cmd_duration` | `10000` ms | +| `__done_notification_urgency_level` | `low` | ### Scrollback History -When running inside Kitty, closing a shell session via exit saves a timestamped -scrollback snapshot to SCROLLBACK_HISTORY_DIR. Files are named: +When running inside Kitty, closing a shell session via `exit` saves a timestamped +scrollback snapshot to `SCROLLBACK_HISTORY_DIR`. Files are named: - scrollback_YYYY-MM-DD_HH-MM-SS.log +`scrollback_YYYY-MM-DD_HH-MM-SS.log` -The paru and yay wrappers (auto-generated in ~/.local/bin/) run the command -inside a PTY via script(1) so download progress bars are preserved on screen, +The `paru` and `yay` wrappers (auto-generated in `~/.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 +`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. Output is saved to: +and preserves ANSI color). If `python3` is unavailable the wrapper falls back to +dropping only the `script(1)` header/footer. Output is saved to: - paru_YYYY-MM-DD_HH-MM-SS.log - yay_YYYY-MM-DD_HH-MM-SS.log +- `paru_YYYY-MM-DD_HH-MM-SS.log` +- `yay_YYYY-MM-DD_HH-MM-SS.log` -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 --no-log (or exit -n) to skip capture. +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 --no-log` (or `exit -n`) to skip capture. --- @@ -2436,67 +2449,63 @@ fish-deps manages these tools. Run `fish-deps` to check status, or ## Required - fish Fish shell >= 4.0 - fzf Fuzzy finder - zoxide Smart cd with frecency +| Tool | Description | +|---|---| +| `fish` | Fish shell >= 4.0 | +| `fzf` | Fuzzy finder | +| `zoxide` | Smart cd with frecency | ## Integrations - wakatime Developer time tracking - tailscale Mesh VPN client +| Tool | Description | +|---|---| +| `wakatime` | Developer time tracking | +| `tailscale` | Mesh VPN client | ## Recommended - 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 — - 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 — used by the paru/yay log cleaner. - Note: uv does not provide python3 on PATH, and Arch'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 — the wrapper falls back to the system yt-dlp and - the rest of the config works without it. +| Tool | Description | +|---|---| +| `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 — 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 — used by the `paru`/`yay` log cleaner. Note: `uv` does not provide `python3` on PATH, and Arch'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 — the wrapper falls back to the system `yt-dlp` and the rest of the config works without it. | ## Install Methods The install priority for each tool: - cargo Rust tools (eza, lsd, bat, dust, ov, ripgrep, trashy, zoxide, - starship) — always gets the latest crate version - system PM paru / apt / brew / dnf / etc. — for tools without a crate - git clone fzf — installed from GitHub to ~/.fzf/ - curl starship installer, fisher bootstrap, uv installer +| Method | Packages | +|---|---| +| `cargo` | Rust tools (`eza`, `lsd`, `bat`, `dust`, `ov`, `ripgrep`, `trashy`, `zoxide`, `starship`) — always gets the latest crate version | +| system PM | `paru` / `apt` / `brew` / `dnf` / etc. — for tools without a crate | +| `git clone` | `fzf` — installed from GitHub to `~/.fzf/` | +| `curl` | `starship` installer, `fisher` bootstrap, `uv` installer | --- # 7. CUSTOMIZATION +This section explains how to adapt the configuration to your specific workflow, including local machine overrides and opinionated component toggles. + ## Machine-local Configuration Place machine-specific settings that should not be committed to git in: @@ -3118,6 +3127,8 @@ local.fish in turn sources secrets.fish when it exists. # 11. TROUBLESHOOTING +This section covers common issues, their solutions, and how to safely revert changes or uninstall the configuration entirely. + ## Uninstalling / Reverting to Backup The installation step backs up any existing config to `~/.config/fish.bak`. diff --git a/docs/manual/01-configuration-variables.md b/docs/manual/01-configuration-variables.md index 7f4fde7..0c2f79d 100644 --- a/docs/manual/01-configuration-variables.md +++ b/docs/manual/01-configuration-variables.md @@ -13,130 +13,143 @@ Override them in local.fish (see Section 10, Personalization). ## Environment Directories (XDG) - XDG_CONFIG_HOME ~/.config - XDG_CACHE_HOME ~/.cache - XDG_DATA_HOME ~/.local/share - XDG_STATE_HOME ~/.local/state +| Variable | Value | +|---|---| +| `XDG_CONFIG_HOME` | `~/.config` | +| `XDG_CACHE_HOME` | `~/.cache` | +| `XDG_DATA_HOME` | `~/.local/share` | +| `XDG_STATE_HOME` | `~/.local/state` | Tools that respect XDG are directed to these paths rather than polluting $HOME. ## Tool Homes (XDG-compliant) - 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 +| Variable | Value | +|---|---| +| `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` | ## Editor and Pager - 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) +| Variable | Value / Notes | +|---|---| +| `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`) | ## Scrollback History - __fish_scrollback_history_dir (unset → ~/.terminal_history) - __fish_scrollback_history_max_files (unset → 100) - SCROLLBACK_HISTORY_DIR ~/.terminal_history (exported mirror) - SCROLLBACK_HISTORY_MAX_FILES 100 (exported mirror) +| Variable | Value / Notes | +|---|---| +| `__fish_scrollback_history_dir` | (unset → `~/.terminal_history`) | +| `__fish_scrollback_history_max_files` | (unset → `100`) | +| `SCROLLBACK_HISTORY_DIR` | `~/.terminal_history` (exported mirror) | +| `SCROLLBACK_HISTORY_MAX_FILES` | `100` (exported mirror) | -The __fish_scrollback_history_* universal variables are the fish-style source +The `__fish_scrollback_history_*` universal variables are the fish-style source of truth — set them via `config-settings` → Paths, or `set -U` 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 +`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. -Scrollback logs accumulate in SCROLLBACK_HISTORY_DIR as timestamped files. -When the count exceeds SCROLLBACK_HISTORY_MAX_FILES the oldest are pruned +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. Use `logs` to browse them interactively. ## Other - GPG_TTY $(tty) — ensures GPG passphrase prompts work - CLAUDE_CODE_NO_FLICKER 1 — suppress terminal flicker in Claude Code - CDPATH . ~/projects ~ +| Variable | Value | Notes | +|---|---|---| +| `GPG_TTY` | `$(tty)` | ensures GPG passphrase prompts work | +| `CLAUDE_CODE_NO_FLICKER` | `1` | suppress terminal flicker in Claude Code | +| `CDPATH` | `. ~/projects ~` | | -Opinionated defaults (CDPATH, PAGER/MANPAGER, Vi mode, command shadows, +Opinionated defaults (`CDPATH`, `PAGER`/`MANPAGER`, Vi mode, command shadows, terminal integrations) can be switched off per category with universal variables — see Section 7, "Opinionated Components (Minimal Mode)". ## Pager Hierarchy -$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 +`$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: - $PAGER → ov → less → more → cat +`$PAGER` → `ov` → `less` → `more` → `cat` -When bat is installed, man pages are rendered with syntax highlighting: +When `bat` is installed, man pages are rendered with syntax highlighting: - MANROFFOPT -c - MANPAGER sh -c 'col -bx | bat -l man -p' +| Variable | Value | +|---|---| +| `MANROFFOPT` | `-c` | +| `MANPAGER` | `sh -c 'col -bx \| bat -l man -p'` | ## Integrations ### Zoxide -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 +`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. ### DirEnv -Automatically loads .envrc files on directory change. Takes priority over -the auto-venv logic — if a directory is managed by direnv, the auto-venv +Automatically loads `.envrc` files on directory change. Takes priority over +the auto-venv logic — if a directory is managed by `direnv`, the auto-venv activation is skipped entirely. ### Auto Python Venv -When entering a directory that contains a .venv/, the virtualenv is activated +When entering a directory that contains a `.venv/`, the virtualenv is activated automatically and deactivated when you leave the project tree. ### WakaTime Every shell command is reported to WakaTime for time-tracking. Set -FISH_WAKATIME_DISABLED=1 to disable without removing the plugin. +`FISH_WAKATIME_DISABLED=1` to disable without removing the plugin. ### Tailscale -Full tab completion for the tailscale CLI is provided via conf.d/tailscale.fish. +Full tab completion for the `tailscale` CLI is provided via `conf.d/tailscale.fish`. ### Done Notifications Desktop notifications fire when a command takes longer than 10 seconds and the terminal window is not focused. Configured via fish universal variables: - __done_min_cmd_duration 10000 ms - __done_notification_urgency_level low +| Variable | Value | +|---|---| +| `__done_min_cmd_duration` | `10000` ms | +| `__done_notification_urgency_level` | `low` | ### Scrollback History -When running inside Kitty, closing a shell session via exit saves a timestamped -scrollback snapshot to SCROLLBACK_HISTORY_DIR. Files are named: +When running inside Kitty, closing a shell session via `exit` saves a timestamped +scrollback snapshot to `SCROLLBACK_HISTORY_DIR`. Files are named: - scrollback_YYYY-MM-DD_HH-MM-SS.log +`scrollback_YYYY-MM-DD_HH-MM-SS.log` -The paru and yay wrappers (auto-generated in ~/.local/bin/) run the command -inside a PTY via script(1) so download progress bars are preserved on screen, +The `paru` and `yay` wrappers (auto-generated in `~/.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 +`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. Output is saved to: +and preserves ANSI color). If `python3` is unavailable the wrapper falls back to +dropping only the `script(1)` header/footer. Output is saved to: - paru_YYYY-MM-DD_HH-MM-SS.log - yay_YYYY-MM-DD_HH-MM-SS.log +- `paru_YYYY-MM-DD_HH-MM-SS.log` +- `yay_YYYY-MM-DD_HH-MM-SS.log` -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 --no-log (or exit -n) to skip capture. +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 --no-log` (or `exit -n`) to skip capture. --- diff --git a/docs/manual/06-dependency-catalog.md b/docs/manual/06-dependency-catalog.md index 2e6ff3c..376f9af 100644 --- a/docs/manual/06-dependency-catalog.md +++ b/docs/manual/06-dependency-catalog.md @@ -13,61 +13,55 @@ fish-deps manages these tools. Run `fish-deps` to check status, or ## Required - fish Fish shell >= 4.0 - fzf Fuzzy finder - zoxide Smart cd with frecency +| Tool | Description | +|---|---| +| `fish` | Fish shell >= 4.0 | +| `fzf` | Fuzzy finder | +| `zoxide` | Smart cd with frecency | ## Integrations - wakatime Developer time tracking - tailscale Mesh VPN client +| Tool | Description | +|---|---| +| `wakatime` | Developer time tracking | +| `tailscale` | Mesh VPN client | ## Recommended - 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 — - 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 — used by the paru/yay log cleaner. - Note: uv does not provide python3 on PATH, and Arch'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 — the wrapper falls back to the system yt-dlp and - the rest of the config works without it. +| Tool | Description | +|---|---| +| `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 — 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 — used by the `paru`/`yay` log cleaner. Note: `uv` does not provide `python3` on PATH, and Arch'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 — the wrapper falls back to the system `yt-dlp` and the rest of the config works without it. | ## Install Methods The install priority for each tool: - cargo Rust tools (eza, lsd, bat, dust, ov, ripgrep, trashy, zoxide, - starship) — always gets the latest crate version - system PM paru / apt / brew / dnf / etc. — for tools without a crate - git clone fzf — installed from GitHub to ~/.fzf/ - curl starship installer, fisher bootstrap, uv installer +| Method | Packages | +|---|---| +| `cargo` | Rust tools (`eza`, `lsd`, `bat`, `dust`, `ov`, `ripgrep`, `trashy`, `zoxide`, `starship`) — always gets the latest crate version | +| system PM | `paru` / `apt` / `brew` / `dnf` / etc. — for tools without a crate | +| `git clone` | `fzf` — installed from GitHub to `~/.fzf/` | +| `curl` | `starship` installer, `fisher` bootstrap, `uv` installer | --- diff --git a/docs/manual/07-customization.md b/docs/manual/07-customization.md index a25006b..81b25d8 100644 --- a/docs/manual/07-customization.md +++ b/docs/manual/07-customization.md @@ -7,6 +7,7 @@ helpKeywords: - customization - customize --- +This section explains how to adapt the configuration to your specific workflow, including local machine overrides and opinionated component toggles. ## Machine-local Configuration diff --git a/docs/manual/11-troubleshooting.md b/docs/manual/11-troubleshooting.md index 25068e4..ab5ae70 100644 --- a/docs/manual/11-troubleshooting.md +++ b/docs/manual/11-troubleshooting.md @@ -12,6 +12,8 @@ helpKeywords: - revert --- +This section covers common issues, their solutions, and how to safely revert changes or uninstall the configuration entirely. + ## Uninstalling / Reverting to Backup The installation step backs up any existing config to `~/.config/fish.bak`.