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

Merge pull request 'docs(catalog): migrate opinionated component catalog into fish-config.md' (#42) from docs/migrate-opinionated-catalog into main
Generate documentation / build-docs (push) Successful in 34s
Details

Browse Source 
Reviewed-on: #42
This commit was merged in pull request #42.
This commit is contained in:
Rootiest
2026-06-11 03:37:26 +00:00
parent e4bcbd3da2 780bda7ab7
commit fc17c9fd61
2 changed files with 196 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/fish-config.index
+19
View File
@@ -71,6 +71,7 @@ mkdir=### mkdir
mkcd=### mkcd
poke=### poke
rm=### rm
rg=### rg
scrub=### scrub
nav-fns=## 5.2 Navigation
cdi=### cdi
@@ -167,6 +168,24 @@ minimal=## Opinionated Components (Minimal Mode)
minimal-mode=## Opinionated Components (Minimal Mode)
opt-out=## Opinionated Components (Minimal Mode)
toggles=## Opinionated Components (Minimal Mode)
component-reference=### Component Reference
components=### Component Reference
c1=#### C1 — Command Shadows
command-shadows=#### C1 — Command Shadows
aliases-detail=#### C1 — Command Shadows
c2=#### C2 — Startup Side-Effects
autoexec=#### C2 — Startup Side-Effects
startup=#### C2 — Startup Side-Effects
c3=#### C3 — Key and Environment Overrides
overrides-detail=#### C3 — Key and Environment Overrides
bang-bang=#### C3 — Key and Environment Overrides
c4=#### C4 — Terminal and Tool Integration
integrations-detail=#### C4 — Terminal and Tool Integration
c5=#### C5 — Logging and Capture
logging-detail=#### C5 — Logging and Capture
logging-sentinel=#### C5 — Logging and Capture
c6=#### C6 — Greeting and First-Run UI
greeting=#### C6 — Greeting and First-Run UI
# ── Section 8: Fisher Plugins ─────────────────────────────────
plugins=# 8. FISHER PLUGINS
docs/fish-config.md
+177
View File
@@ -613,6 +613,17 @@ Add -i (interactive confirmation) to destructive commands:
rm -e # empty trash
rm -S sensitive.pem # permanent delete
### rg
Synopsis: rg [args...]
In Kitty, wraps ripgrep with --hyperlink-format=kitty so search
results are clickable file links in the terminal. Falls back to
system rg in any other terminal. All other arguments pass through
unchanged.
rg "fish_greeting" ~/.config/fish/
rg -l "TODO" ~/projects/myapp
### scrub
Synopsis: scrub [-a] [-d] [-h]
@@ -1454,6 +1465,172 @@ Notes:
- On CachyOS, the distro fish config's own aliases, history override,
and bang-bang bindings are stripped per category as well.
### Component Reference
The following tables detail every component in each category. Use this
reference to understand exactly which behaviors change when you toggle a
category variable.
#### C1 — Command Shadows
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 help
When C1 is disabled, `rm` uses bare `command rm` with no wrapper — files
are permanently deleted, not trashed. There is no intermediate safety net.
#### C2 — Startup Side-Effects
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 API
When 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.
#### C3 — Key and Environment Overrides
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 + timestamp
The 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).
#### C4 — Terminal and Tool Integration
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 key
Disabled integration commands (spwin, tab, split, hist, logs, upgrade) print
a colored error to stderr naming the variable that disabled them rather than
silently failing.
#### C5 — Logging and Capture
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 teed to:
~/.terminal_history/paru_YYYY-MM-DD_HH-MM-SS.log
yay wrapper All yay/AUR output teed to:
~/.terminal_history/yay_YYYY-MM-DD_HH-MM-SS.log
Kitty watcher watcher.py captures scrollback when Kitty closes
Logging 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_disabled
Disabling __fish_config_op_logging:
1. Creates the sentinel immediately in every open shell.
2. Removes ~/.local/bin/paru and ~/.local/bin/yay logging wrappers;
bare /usr/bin/paru and /usr/bin/yay are used instead.
3. Kitty's watcher.py reads the sentinel on each save attempt and
skips capture — no Kitty restart required.
4. smart_exit stops saving scrollback logs.
Re-enabling __fish_config_op_logging:
1. Removes the sentinel in every open shell.
2. Regenerates paru/yay logging wrappers in ~/.local/bin/.
3. Kitty watcher resumes capture on the next session exit.
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.
#### C6 — Greeting and First-Run UI
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.
## Prompt and Theme
### Starship