fish-config/docs/wiki/1-configuration-variables.md

1. CONFIGURATION VARIABLES

Sections: Index | 1. Configuration Variables | 2. Path Setup | 3. Key Bindings | 4. Abbreviations | 5. Functions Reference | 6. Dependency Catalog | 7. Customization | 8. Fisher Plugins | 9. Installation | 10. Personalization | 11. Viewing This Manual

---

These variables are exported from config.fish on every interactive session. 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

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

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)

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)

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 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 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 ~

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 also benefits:

$PAGER → ov → less → more → cat

When bat is installed, man pages are rendered with syntax highlighting:

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 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 activation is skipped entirely.

Auto Python Venv

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.

Tailscale

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

Scrollback History

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

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 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:

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.

---