diff --git a/docs/fish-config.index b/docs/fish-config.index index b39e85d..f999958 100644 --- a/docs/fish-config.index +++ b/docs/fish-config.index @@ -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 diff --git a/docs/fish-config.md b/docs/fish-config.md index 74fc532..74ff4b0 100644 --- a/docs/fish-config.md +++ b/docs/fish-config.md @@ -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