rootiest/fish-config
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: reformat catalog/vars to standard markdown and add intros
Generate documentation / build-docs (push) Successful in 3m16s
Details

Browse Source 
Fixed tables and text formatting in the Dependency Catalog and Configuration Variables pages so they render properly as markdown instead of flat code blocks. Added introductory sentences to Troubleshooting and Customization so the Starlight sub-heading navigation cards get injected at the top of the page rather than jumping below the first heading.
This commit is contained in:
Rootiest
2026-07-27 00:55:41 -04:00
parent e63fd8b525
commit d6c37fe0ad
5 changed files with 229 additions and 208 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/fish-config.md
+115 -104
View File
@@ -148,131 +148,144 @@ Override them in local.fish (see Section 10, Personalization).
## Environment Directories (XDG) ## Environment Directories (XDG)
XDG_CONFIG_HOME ~/.config | Variable | Value |
XDG_CACHE_HOME ~/.cache |---|---|
XDG_DATA_HOME ~/.local/share | `XDG_CONFIG_HOME` | `~/.config` |
XDG_STATE_HOME ~/.local/state | `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. Tools that respect XDG are directed to these paths rather than polluting $HOME.
## Tool Homes (XDG-compliant) ## Tool Homes (XDG-compliant)
CARGO_HOME $XDG_DATA_HOME/cargo | Variable | Value |
RUSTUP_HOME $XDG_DATA_HOME/rustup |---|---|
GOPATH $XDG_DATA_HOME/go | `CARGO_HOME` | `$XDG_DATA_HOME/cargo` |
BUN_INSTALL $XDG_DATA_HOME/bun | `RUSTUP_HOME` | `$XDG_DATA_HOME/rustup` |
NPM_CONFIG_PREFIX $XDG_DATA_HOME/npm-global | `GOPATH` | `$XDG_DATA_HOME/go` |
GNUPGHOME $XDG_CONFIG_HOME/gnupg | `BUN_INSTALL` | `$XDG_DATA_HOME/bun` |
WAKATIME_HOME $XDG_CONFIG_HOME/wakatime | `NPM_CONFIG_PREFIX` | `$XDG_DATA_HOME/npm-global` |
| `GNUPGHOME` | `$XDG_CONFIG_HOME/gnupg` |
| `WAKATIME_HOME` | `$XDG_CONFIG_HOME/wakatime` |
## Editor and Pager ## Editor and Pager
EDITOR nvim (falls back to vi if nvim is absent) | Variable | Value / Notes |
VISUAL unset by default; set a GUI editor via local.fish (the edit |---|---|
function falls back to a GUI chain when VISUAL is empty) | `EDITOR` | `nvim` (falls back to `vi` if `nvim` is absent) |
SUDO_EDITOR same as EDITOR | `VISUAL` | unset by default; set a GUI editor via `local.fish` (the `edit` function falls back to a GUI chain when `VISUAL` is empty) |
PAGER ov (falls back to less) | `SUDO_EDITOR` | same as `EDITOR` |
| `PAGER` | `ov` (falls back to `less`) |
## Scrollback History ## Scrollback History
__fish_scrollback_history_dir (unset → ~/.terminal_history) | Variable | Value / Notes |
__fish_scrollback_history_max_files (unset → 100) |---|---|
SCROLLBACK_HISTORY_DIR ~/.terminal_history (exported mirror) | `__fish_scrollback_history_dir` | (unset → `~/.terminal_history`) |
SCROLLBACK_HISTORY_MAX_FILES 100 (exported mirror) | `__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. of truth — set them via `config-settings` → Paths, or `set -U` directly.
config.fish exports the SCROLLBACK_HISTORY_* mirrors from them, because the `config.fish` exports the `SCROLLBACK_HISTORY_*` mirrors from them, because the
POSIX wrapper scripts (paru/yay/tmux/zellij logging and _prune_terminal_logs) 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, read the exported names from the environment. When the `__fish_` vars are unset,
the documented defaults are exported. config.fish deliberately does not create 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 a global source var, which would shadow the universal and stop live edits from
taking effect. taking effect.
Scrollback logs accumulate in SCROLLBACK_HISTORY_DIR as timestamped files. Scrollback logs accumulate in `SCROLLBACK_HISTORY_DIR` as timestamped files.
When the count exceeds SCROLLBACK_HISTORY_MAX_FILES the oldest are pruned When the count exceeds `SCROLLBACK_HISTORY_MAX_FILES` the oldest are pruned
automatically on exit. Use `logs` to browse them interactively. automatically on exit. Use `logs` to browse them interactively.
## Other ## Other
GPG_TTY $(tty) — ensures GPG passphrase prompts work | Variable | Value | Notes |
CLAUDE_CODE_NO_FLICKER 1 — suppress terminal flicker in Claude Code |---|---|---|
CDPATH . ~/projects ~ | `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 terminal integrations) can be switched off per category with universal
variables — see Section 7, "Opinionated Components (Minimal Mode)". variables — see Section 7, "Opinionated Components (Minimal Mode)".
## Pager Hierarchy ## Pager Hierarchy
$PAGER is set to ov when available, falling back to less. The less wrapper `$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 function extends this into a full chain so anything that calls `less` directly
also benefits: 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 | Variable | Value |
MANPAGER sh -c 'col -bx | bat -l man -p' |---|---|
| `MANROFFOPT` | `-c` |
| `MANPAGER` | `sh -c 'col -bx \| bat -l man -p'` |
## Integrations ## Integrations
### Zoxide ### Zoxide
cd, z, and cdi/zi are all mapped to zoxide-backed navigation. Tab completions `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 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. results so both familiar and frequently-visited paths appear in one list.
### DirEnv ### DirEnv
Automatically loads .envrc files on directory change. Takes priority over Automatically loads `.envrc` files on directory change. Takes priority over
the auto-venv logic — if a directory is managed by direnv, the auto-venv the auto-venv logic — if a directory is managed by `direnv`, the auto-venv
activation is skipped entirely. activation is skipped entirely.
### Auto Python Venv ### 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. automatically and deactivated when you leave the project tree.
### WakaTime ### WakaTime
Every shell command is reported to WakaTime for time-tracking. Set 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 ### 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 ### Done Notifications
Desktop notifications fire when a command takes longer than 10 seconds and Desktop notifications fire when a command takes longer than 10 seconds and
the terminal window is not focused. Configured via fish universal variables: the terminal window is not focused. Configured via fish universal variables:
__done_min_cmd_duration 10000 ms | Variable | Value |
__done_notification_urgency_level low |---|---|
| `__done_min_cmd_duration` | `10000` ms |
| `__done_notification_urgency_level` | `low` |
### Scrollback History ### Scrollback History
When running inside Kitty, closing a shell session via exit saves a timestamped When running inside Kitty, closing a shell session via `exit` saves a timestamped
scrollback snapshot to SCROLLBACK_HISTORY_DIR. Files are named: 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 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, 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 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, cursor movements, collapses repainted progress frames to their final state,
and preserves ANSI color). If python3 is unavailable the wrapper falls back 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: dropping only the `script(1)` header/footer. Output is saved to:
paru_YYYY-MM-DD_HH-MM-SS.log - `paru_YYYY-MM-DD_HH-MM-SS.log`
yay_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 Before pruning, `_scrollback_prune_junk` silently removes empty files, files
with only a single meaningful line (e.g. bare [exited] captures), and Kitty 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. 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 ## Required
fish Fish shell >= 4.0 | Tool | Description |
fzf Fuzzy finder |---|---|
zoxide Smart cd with frecency | `fish` | Fish shell >= 4.0 |
| `fzf` | Fuzzy finder |
| `zoxide` | Smart cd with frecency |
## Integrations ## Integrations
wakatime Developer time tracking | Tool | Description |
tailscale Mesh VPN client |---|---|
| `wakatime` | Developer time tracking |
| `tailscale` | Mesh VPN client |
## Recommended ## Recommended
cargo Rust toolchain (via rustup); used by fish-deps to install | Tool | Description |
Rust-based tools and to build fish from source. All paths |---|---|
are gated on type -q cargo and degrade gracefully. | `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. | `starship` | Cross-shell prompt; loaded via `type -q starship` guard. Without it the Catppuccin nim-style fallback prompt activates. |
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. |
uv Python package and project manager (Astral); used by the | `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. |
fish-from-source build path in fish-deps. All consumers | `paru` | AUR helper (Arch only; preferred); guarded throughout — non-Arch systems silently skip AUR-specific paths. |
degrade gracefully without it. | `yay` | AUR helper (Arch only; fallback to paru); same guards apply. |
direnv Per-directory environment loading; integration is fully | `eza` | Modern `ls` replacement |
guarded with type -q direnv. Without it the direnv hook | `lsd` | `ls` replacement (fallback to `eza`) |
is simply not loaded and auto-venv activates normally. | `bat` | Syntax-highlighted `cat` |
paru AUR helper (Arch only; preferred); guarded throughout — | `btop` | Modern resource monitor |
non-Arch systems silently skip AUR-specific paths. | `dust` | Disk usage tree (Rust) |
yay AUR helper (Arch only; fallback to paru); same guards apply. | `duf` | Disk usage/free overview |
eza Modern ls replacement | `prettyping` | Colorized ping wrapper |
lsd ls replacement (fallback to eza) | `ov` | Modern pager (replaces `less`) |
bat Syntax-highlighted cat | `ripgrep` | Fast line search |
btop Modern resource monitor | `lazygit` | Terminal git UI |
dust Disk usage tree (Rust) | `lazydocker` | Terminal docker UI |
duf Disk usage/free overview | `trash` | Safe delete (`trash-cli`) |
prettyping Colorized ping wrapper | `kitty` | GPU-accelerated terminal (primary) |
ov Modern pager (replaces less) | `wezterm` | GPU-accelerated terminal (alternative) |
ripgrep Fast line search | `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. |
lazygit Terminal git UI | `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. |
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 ## Install Methods
The install priority for each tool: The install priority for each tool:
cargo Rust tools (eza, lsd, bat, dust, ov, ripgrep, trashy, zoxide, | Method | Packages |
starship) — always gets the latest crate version |---|---|
system PM paru / apt / brew / dnf / etc. — for tools without a crate | `cargo` | Rust tools (`eza`, `lsd`, `bat`, `dust`, `ov`, `ripgrep`, `trashy`, `zoxide`, `starship`) — always gets the latest crate version |
git clone fzf — installed from GitHub to ~/.fzf/ | system PM | `paru` / `apt` / `brew` / `dnf` / etc. — for tools without a crate |
curl starship installer, fisher bootstrap, uv installer | `git clone` | `fzf` — installed from GitHub to `~/.fzf/` |
| `curl` | `starship` installer, `fisher` bootstrap, `uv` installer |
--- ---
# 7. CUSTOMIZATION # 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 ## Machine-local Configuration
Place machine-specific settings that should not be committed to git in: 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 # 11. TROUBLESHOOTING
This section covers common issues, their solutions, and how to safely revert changes or uninstall the configuration entirely.
## Uninstalling / Reverting to Backup ## Uninstalling / Reverting to Backup
The installation step backs up any existing config to `~/.config/fish.bak`. The installation step backs up any existing config to `~/.config/fish.bak`.
docs/manual/01-configuration-variables.md
+72 -59
View File
@@ -13,130 +13,143 @@ Override them in local.fish (see Section 10, Personalization).
## Environment Directories (XDG) ## Environment Directories (XDG)
XDG_CONFIG_HOME ~/.config | Variable | Value |
XDG_CACHE_HOME ~/.cache |---|---|
XDG_DATA_HOME ~/.local/share | `XDG_CONFIG_HOME` | `~/.config` |
XDG_STATE_HOME ~/.local/state | `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. Tools that respect XDG are directed to these paths rather than polluting $HOME.
## Tool Homes (XDG-compliant) ## Tool Homes (XDG-compliant)
CARGO_HOME $XDG_DATA_HOME/cargo | Variable | Value |
RUSTUP_HOME $XDG_DATA_HOME/rustup |---|---|
GOPATH $XDG_DATA_HOME/go | `CARGO_HOME` | `$XDG_DATA_HOME/cargo` |
BUN_INSTALL $XDG_DATA_HOME/bun | `RUSTUP_HOME` | `$XDG_DATA_HOME/rustup` |
NPM_CONFIG_PREFIX $XDG_DATA_HOME/npm-global | `GOPATH` | `$XDG_DATA_HOME/go` |
GNUPGHOME $XDG_CONFIG_HOME/gnupg | `BUN_INSTALL` | `$XDG_DATA_HOME/bun` |
WAKATIME_HOME $XDG_CONFIG_HOME/wakatime | `NPM_CONFIG_PREFIX` | `$XDG_DATA_HOME/npm-global` |
| `GNUPGHOME` | `$XDG_CONFIG_HOME/gnupg` |
| `WAKATIME_HOME` | `$XDG_CONFIG_HOME/wakatime` |
## Editor and Pager ## Editor and Pager
EDITOR nvim (falls back to vi if nvim is absent) | Variable | Value / Notes |
VISUAL unset by default; set a GUI editor via local.fish (the edit |---|---|
function falls back to a GUI chain when VISUAL is empty) | `EDITOR` | `nvim` (falls back to `vi` if `nvim` is absent) |
SUDO_EDITOR same as EDITOR | `VISUAL` | unset by default; set a GUI editor via `local.fish` (the `edit` function falls back to a GUI chain when `VISUAL` is empty) |
PAGER ov (falls back to less) | `SUDO_EDITOR` | same as `EDITOR` |
| `PAGER` | `ov` (falls back to `less`) |
## Scrollback History ## Scrollback History
__fish_scrollback_history_dir (unset → ~/.terminal_history) | Variable | Value / Notes |
__fish_scrollback_history_max_files (unset → 100) |---|---|
SCROLLBACK_HISTORY_DIR ~/.terminal_history (exported mirror) | `__fish_scrollback_history_dir` | (unset → `~/.terminal_history`) |
SCROLLBACK_HISTORY_MAX_FILES 100 (exported mirror) | `__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. of truth — set them via `config-settings` → Paths, or `set -U` directly.
config.fish exports the SCROLLBACK_HISTORY_* mirrors from them, because the `config.fish` exports the `SCROLLBACK_HISTORY_*` mirrors from them, because the
POSIX wrapper scripts (paru/yay/tmux/zellij logging and _prune_terminal_logs) 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, read the exported names from the environment. When the `__fish_` vars are unset,
the documented defaults are exported. config.fish deliberately does not create 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 a global source var, which would shadow the universal and stop live edits from
taking effect. taking effect.
Scrollback logs accumulate in SCROLLBACK_HISTORY_DIR as timestamped files. Scrollback logs accumulate in `SCROLLBACK_HISTORY_DIR` as timestamped files.
When the count exceeds SCROLLBACK_HISTORY_MAX_FILES the oldest are pruned When the count exceeds `SCROLLBACK_HISTORY_MAX_FILES` the oldest are pruned
automatically on exit. Use `logs` to browse them interactively. automatically on exit. Use `logs` to browse them interactively.
## Other ## Other
GPG_TTY $(tty) — ensures GPG passphrase prompts work | Variable | Value | Notes |
CLAUDE_CODE_NO_FLICKER 1 — suppress terminal flicker in Claude Code |---|---|---|
CDPATH . ~/projects ~ | `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 terminal integrations) can be switched off per category with universal
variables — see Section 7, "Opinionated Components (Minimal Mode)". variables — see Section 7, "Opinionated Components (Minimal Mode)".
## Pager Hierarchy ## Pager Hierarchy
$PAGER is set to ov when available, falling back to less. The less wrapper `$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 function extends this into a full chain so anything that calls `less` directly
also benefits: 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 | Variable | Value |
MANPAGER sh -c 'col -bx | bat -l man -p' |---|---|
| `MANROFFOPT` | `-c` |
| `MANPAGER` | `sh -c 'col -bx \| bat -l man -p'` |
## Integrations ## Integrations
### Zoxide ### Zoxide
cd, z, and cdi/zi are all mapped to zoxide-backed navigation. Tab completions `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 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. results so both familiar and frequently-visited paths appear in one list.
### DirEnv ### DirEnv
Automatically loads .envrc files on directory change. Takes priority over Automatically loads `.envrc` files on directory change. Takes priority over
the auto-venv logic — if a directory is managed by direnv, the auto-venv the auto-venv logic — if a directory is managed by `direnv`, the auto-venv
activation is skipped entirely. activation is skipped entirely.
### Auto Python Venv ### 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. automatically and deactivated when you leave the project tree.
### WakaTime ### WakaTime
Every shell command is reported to WakaTime for time-tracking. Set 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 ### 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 ### Done Notifications
Desktop notifications fire when a command takes longer than 10 seconds and Desktop notifications fire when a command takes longer than 10 seconds and
the terminal window is not focused. Configured via fish universal variables: the terminal window is not focused. Configured via fish universal variables:
__done_min_cmd_duration 10000 ms | Variable | Value |
__done_notification_urgency_level low |---|---|
| `__done_min_cmd_duration` | `10000` ms |
| `__done_notification_urgency_level` | `low` |
### Scrollback History ### Scrollback History
When running inside Kitty, closing a shell session via exit saves a timestamped When running inside Kitty, closing a shell session via `exit` saves a timestamped
scrollback snapshot to SCROLLBACK_HISTORY_DIR. Files are named: 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 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, 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 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, cursor movements, collapses repainted progress frames to their final state,
and preserves ANSI color). If python3 is unavailable the wrapper falls back 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: dropping only the `script(1)` header/footer. Output is saved to:
paru_YYYY-MM-DD_HH-MM-SS.log - `paru_YYYY-MM-DD_HH-MM-SS.log`
yay_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 Before pruning, `_scrollback_prune_junk` silently removes empty files, files
with only a single meaningful line (e.g. bare [exited] captures), and Kitty 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. tab-rename prompt captures. Use `exit --no-log` (or `exit -n`) to skip capture.
--- ---
docs/manual/06-dependency-catalog.md
+39 -45
View File
@@ -13,61 +13,55 @@ fish-deps manages these tools. Run `fish-deps` to check status, or
## Required ## Required
fish Fish shell >= 4.0 | Tool | Description |
fzf Fuzzy finder |---|---|
zoxide Smart cd with frecency | `fish` | Fish shell >= 4.0 |
| `fzf` | Fuzzy finder |
| `zoxide` | Smart cd with frecency |
## Integrations ## Integrations
wakatime Developer time tracking | Tool | Description |
tailscale Mesh VPN client |---|---|
| `wakatime` | Developer time tracking |
| `tailscale` | Mesh VPN client |
## Recommended ## Recommended
cargo Rust toolchain (via rustup); used by fish-deps to install | Tool | Description |
Rust-based tools and to build fish from source. All paths |---|---|
are gated on type -q cargo and degrade gracefully. | `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. | `starship` | Cross-shell prompt; loaded via `type -q starship` guard. Without it the Catppuccin nim-style fallback prompt activates. |
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. |
uv Python package and project manager (Astral); used by the | `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. |
fish-from-source build path in fish-deps. All consumers | `paru` | AUR helper (Arch only; preferred); guarded throughout — non-Arch systems silently skip AUR-specific paths. |
degrade gracefully without it. | `yay` | AUR helper (Arch only; fallback to paru); same guards apply. |
direnv Per-directory environment loading; integration is fully | `eza` | Modern `ls` replacement |
guarded with type -q direnv. Without it the direnv hook | `lsd` | `ls` replacement (fallback to `eza`) |
is simply not loaded and auto-venv activates normally. | `bat` | Syntax-highlighted `cat` |
paru AUR helper (Arch only; preferred); guarded throughout — | `btop` | Modern resource monitor |
non-Arch systems silently skip AUR-specific paths. | `dust` | Disk usage tree (Rust) |
yay AUR helper (Arch only; fallback to paru); same guards apply. | `duf` | Disk usage/free overview |
eza Modern ls replacement | `prettyping` | Colorized ping wrapper |
lsd ls replacement (fallback to eza) | `ov` | Modern pager (replaces `less`) |
bat Syntax-highlighted cat | `ripgrep` | Fast line search |
btop Modern resource monitor | `lazygit` | Terminal git UI |
dust Disk usage tree (Rust) | `lazydocker` | Terminal docker UI |
duf Disk usage/free overview | `trash` | Safe delete (`trash-cli`) |
prettyping Colorized ping wrapper | `kitty` | GPU-accelerated terminal (primary) |
ov Modern pager (replaces less) | `wezterm` | GPU-accelerated terminal (alternative) |
ripgrep Fast line search | `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. |
lazygit Terminal git UI | `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. |
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 ## Install Methods
The install priority for each tool: The install priority for each tool:
cargo Rust tools (eza, lsd, bat, dust, ov, ripgrep, trashy, zoxide, | Method | Packages |
starship) — always gets the latest crate version |---|---|
system PM paru / apt / brew / dnf / etc. — for tools without a crate | `cargo` | Rust tools (`eza`, `lsd`, `bat`, `dust`, `ov`, `ripgrep`, `trashy`, `zoxide`, `starship`) — always gets the latest crate version |
git clone fzf — installed from GitHub to ~/.fzf/ | system PM | `paru` / `apt` / `brew` / `dnf` / etc. — for tools without a crate |
curl starship installer, fisher bootstrap, uv installer | `git clone` | `fzf` — installed from GitHub to `~/.fzf/` |
| `curl` | `starship` installer, `fisher` bootstrap, `uv` installer |
--- ---
docs/manual/07-customization.md
+1
View File
@@ -7,6 +7,7 @@ helpKeywords:
- customization - customization
- customize - customize
--- ---
This section explains how to adapt the configuration to your specific workflow, including local machine overrides and opinionated component toggles.
## Machine-local Configuration ## Machine-local Configuration
docs/manual/11-troubleshooting.md
+2
View File
@@ -12,6 +12,8 @@ helpKeywords:
- revert - revert
--- ---
This section covers common issues, their solutions, and how to safely revert changes or uninstall the configuration entirely.
## Uninstalling / Reverting to Backup ## Uninstalling / Reverting to Backup
The installation step backs up any existing config to `~/.config/fish.bak`. The installation step backs up any existing config to `~/.config/fish.bak`.