docs: reformat catalog/vars to standard markdown and add intros
Generate documentation / build-docs (push) Successful in 3m16s
Generate documentation / build-docs (push) Successful in 3m16s
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:
+115
-104
@@ -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`.
|
||||
|
||||
@@ -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.
|
||||
|
||||
---
|
||||
|
||||
@@ -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 |
|
||||
|
||||
---
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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`.
|
||||
|
||||
Reference in New Issue
Block a user