Place machine-specific settings that should not be committed to git in:
~/.config/.user-dots/fish/local.fishTypical uses: additional PATH entries, local aliases, hostname-specific env vars, work-specific tool configs.
~/.config/.user-dots/fish/secrets.fishStore API tokens, GPG keys, private credentials here. This file is never committed.
Both files are sourced at the end of config.fish on every interactive session, so they can override anything set earlier.
Any variable set in local.fish after the main config loads takes effect. Example: to increase the scrollback history limit:
# in local.fish
set -gx SCROLLBACK_HISTORY_MAX_FILES 200Some settings (fzf colors, theme) are stored in fish_variables via
set -U. These are machine-local and git-ignored. Do not
commit fish_variables.
Every opinionated piece of this config is active by default but can be switched off through six category opt-out variables, each evaluated via __fish_variable_check. Set a variable to any falsy value (0, false, no, off, n) to disable its category; erase it or set a truthy value (1, true, yes, on, y) to re-enable. Unset means enabled.
An explicit per-category truthy value takes precedence over the master switch: setting __fish_config_opinionated=0 disables all unset categories, but a category with an explicit truthy value remains enabled regardless.
Variable Disables
------------------------------ ------------------------------------
__fish_config_op_aliases Command shadows and flag injection:
ls->eza, cat->bat, cd->zoxide,
rm->trash, less->ov, top->btop,
ping->prettyping, ssh->kitten,
du->duf/dust, mkdir/bash wrappers,
history timestamps, grep/cp/mv/wget
flag injection, help intercept
__fish_config_op_autoexec Startup side-effects: Fisher
bootstrap, theme apply, paru/yay
wrapper generation, auto venv
activation, WakaTime hook
__fish_config_op_overrides Key and env overrides: Vi mode,
exit->smart_exit, PAGER/MANPAGER,
CDPATH, bang-bang system, autopair,
puffer, starship prompt, theme
colors, FZF_DEFAULT_OPTS, right
prompt
__fish_config_op_integrations Terminal/tool coupling: Kitty/
WezTerm window abbreviations, done
notifications, spwin/tab/split,
hist, logs, upgrade, WakaTime
__fish_config_op_logging Logging & capture: scrollback
capture on exit, paru/yay AUR log
wrappers, Kitty watcher capture;
sentinel file coordinates
cross-process state
__fish_config_op_greeting Greeting & first-run UI: per-session
fish_greeting override (defines empty
function late in config.fish to
suppress distro greetings such as
CachyOS fastfetch); first-run welcome
banner in conf.d/first_run.fishExamples:
# Disable command shadows only (rm becomes plain rm again):
set -U __fish_config_op_aliases off
# Full minimal mode — disable all six categories at once:
set -U __fish_config_opinionated 0
# Re-enable everything:
set -Ue __fish_config_opinionated
# Minimal mode but keep the greeting:
set -U __fish_config_opinionated 0
set -U __fish_config_op_greeting 1
# (erase both to go back to full-flavor defaults)Notes:
command rm
— files are deleted permanently, not trashed.The following tables detail every component in each category. Use this reference to understand exactly which behaviors change when you toggle a category variable.
Disabling __fish_config_op_aliases restores standard system behavior for all of these commands.
Command / Alias Active behavior Disabled fallback
───────────────────────────────────────────────────────────────────────────
ls eza -l -a --icons --hyperlink system ls
cat bat syntax-highlighted; dirs → ls /usr/bin/cat
cd zoxide frecency-based navigation fish builtin cd
rm moves files to trash (recoverable) command rm (permanent)
less $PAGER → ov → less → more → cat system less
du duf (disk overview) or dust (dir tree) system du
top btop resource monitor system top
ping prettyping --nolegend animation system ping
ssh kitten ssh in Kitty terminal system ssh
rg rg --hyperlink-format=kitty system rg
mkdir verbose path-tree display on creation mkdir -p silently
bash XDG bashrc + $SHELL reset on exit system bash
history timestamps prepended to every entry fish builtin history
cp / mv forced -i confirmation prompt cp / mv unmodified
wget forced --continue (resume downloads) system wget
grep/fgrep/egrep forced --color=auto system grep variants
dir / vdir forced --color=auto system dir / vdir
help config intercepts "help config" → config-help fish builtin helpWhen C1 is disabled, rm uses bare
command rm with no wrapper — files are permanently deleted,
not trashed. There is no intermediate safety net.
These run automatically without any user action. Disabling __fish_config_op_autoexec prevents all of them.
Component Trigger What it does
───────────────────────────────────────────────────────────────────────────
Fisher bootstrap First shell only Downloads and installs fisher
Fisher update After bootstrap Installs all fish_plugins entries
Catppuccin Mocha theme First shell only Applies theme via fish_config
paru wrapper Every startup Writes ~/.local/bin/paru wrapper
yay wrapper Every startup Writes ~/.local/bin/yay wrapper
Python venv activation On every cd Sources .venv/bin/activate.fish
WakaTime command hook On every command Reports to WakaTime APIWhen C2 is disabled: no Fisher install, no theme application, no paru/yay wrapper generation, no automatic venv activation, and no WakaTime reporting. The first-run completion marker (__fish_config_first_run_complete) is still set so the init does not re-run on subsequent shells.
Python venv activation fires on every directory change. If a directory uses direnv (.envrc present), direnv takes priority and auto-venv is skipped for that directory.
These change fundamental shell behavior: how keys work, which pager opens, and what the prompt looks like. Disabling __fish_config_op_overrides removes all of them.
Override What it replaces or sets
───────────────────────────────────────────────────────────────────────────
Vi mode fish_vi_key_bindings replaces default Emacs mode
exit → smart_exit exit wrapper that captures scrollback before closing
PAGER=ov ov used by git, man, and all $PAGER-aware tools
MANPAGER=bat pipeline man pages rendered with syntax highlighting
CDPATH=. ~/projects ~ bare dir names resolve against ~/projects and ~
Bang-bang system ! and $ keys expand history; !^, !*, !-N, !?str?,
^old^new abbreviations; six expand_bang_* helpers
Autopair ( [ { " ' auto-close to (), [], {}, "", ''
Puffer key intercepts . ! $ * keys intercepted for smart expansion
Starship prompt fish_prompt replaced by Starship + OSC 133 markers
Catppuccin colors 30+ fish_color_* variables set to Mocha palette
FZF_DEFAULT_OPTS FZF themed to Catppuccin Mocha colors
Right prompt fish_right_prompt: Docker context + timestampThe bang-bang system spans key_bindings.fish, abbr.fish, puffer.fish, and six expand_bang_*.fish functions. All are gated together — disabling C3 removes the entire bang-expansion system at once.
When C3 is disabled, exit falls back to
builtin exit with no scrollback capture, no Kitty IPC, and
no file I/O on exit. The scrollback capture block is independently
controlled by C5 (see below).
These features couple the shell to specific external tools. Disabling __fish_config_op_integrations disables all of them.
Component Requires
───────────────────────────────────────────────────────────────────────────
~60 Kitty/WezTerm abbrs Active Kitty or WezTerm session
(:w, :wv, :wh, :t, etc.)
Done desktop notifications Graphical desktop with a notification daemon
spwin Kitty or WezTerm
tab Kitty, WezTerm, or Konsole
split Kitty or WezTerm
hist fzf + wl-copy (Wayland clipboard)
logs fzf + ov; reads from ~/.terminal_history/
upgrade paru or yay (Arch Linux only)
WakaTime hook wakatime CLI and a configured API keyDisabled integration commands (spwin, tab, split, hist, logs, upgrade) print a colored error to stderr naming the variable that disabled them rather than silently failing.
Three components capture shell output to disk. Disabling __fish_config_op_logging skips all capture and removes the logging wrappers.
Component What it captures
───────────────────────────────────────────────────────────────────────────
Scrollback capture Terminal session output saved to:
~/.terminal_history/scrollback_YYYY-MM-DD_HH-MM-SS.log
paru wrapper All paru/AUR output captured to:
~/.terminal_history/paru_YYYY-MM-DD_HH-MM-SS.log
yay wrapper All yay/AUR output captured to:
~/.terminal_history/yay_YYYY-MM-DD_HH-MM-SS.log
Kitty watcher watcher.py captures scrollback when Kitty closesLogging coordination via sentinel file
C5 uses a sentinel file to synchronize state between the shell and out-of-process components (the Kitty watcher and all running shells):
~/.config/fish/.logging_disabledDisabling __fish_config_op_logging:
Re-enabling __fish_config_op_logging:
Changes propagate to all running shells through an event handler that fires whenever __fish_config_op_logging changes — no shell restart needed.
Note: C3 and C5 compose independently. C3 controls whether the smart_exit wrapper is active at all; C5 controls only the scrollback-capture block inside it. With C3 disabled, exit is plain builtin exit regardless of C5.
Component What it shows
───────────────────────────────────────────────────────────────────────────
First-run welcome banner One-time message on first interactive session
fish_greeting override Empty function defined late in config.fish to
suppress distro greetings (e.g. CachyOS sets
fish_greeting to fastfetch by default)When C6 is disabled, no greeting is printed by this config. Any greeting set by the distro or other configs runs normally — this config simply does not override it.
The primary prompt is Starship, initialized by conf.d/starship.fish. Configure it via ~/.config/starship.toml.
conf.d/starship.fish defines a fish_prompt wrapper that only activates when starship is in PATH. It emits OSC 133;A (prompt start) immediately before Starship renders and OSC 133;B (input start) immediately after, placing both markers on the prompt line itself. This allows ov to use them as sticky section headers when browsing scrollback logs. Without Starship, fish's built-in prompt handles these markers automatically.
FZF is themed to Catppuccin Mocha via FZF_DEFAULT_OPTS set in integrations/fzf.fish. The colors applied:
Background: #1E1E2E (base) #313244 (surface0)
Foreground: #CDD6F4 (text)
Highlights: #F38BA8 (red) #CBA6F7 (mauve) #B4BEFE (lavender)To customize, override FZF_DEFAULT_OPTS in local.fish.
The Catppuccin Mocha theme ships with this config in themes/ and is
applied on first run via conf.d/first_run.fish. Colors are
stored in fish_variables (universal). To switch variants, install a
different theme from themes/:
fish_config theme save "Catppuccin Latte"