From dd28fc784b2dc3484e02252229fe7618559be916 Mon Sep 17 00:00:00 2001 From: rootiest Date: Mon, 27 Jul 2026 20:49:40 -0400 Subject: [PATCH] docs: restructure customization and components reference into nested directories --- docs/fish-config.index | 90 ++-- docs/fish-config.md | 154 +++--- docs/manual/07-customization.md | 463 ------------------ .../01-machine-local-configuration.md | 24 + .../02-secrets-and-api-keys.md | 13 + .../03-overriding-configuration-variables.md | 10 + .../04-fish-universal-variables.md | 8 + .../05-opinionated-components-minimal-mode.md | 86 ++++ .../07-customization/06-prompt-and-theme.md | 66 +++ docs/manual/07-customization/index.md | 11 + .../01-c1-command-shadows.md | 33 ++ .../02-c2-startup-side-effects.md | 45 ++ .../03-c3-key-and-environment-overrides.md | 35 ++ .../04-c4-terminal-and-tool-integration.md | 24 + .../05-c5-logging-and-capture.md | 112 +++++ .../06-c6-greeting-and-first-run-ui.md | 15 + docs/manual/08-components-reference/index.md | 12 + ...fisher-plugins.md => 09-fisher-plugins.md} | 4 +- ...{09-installation.md => 10-installation.md} | 4 +- ...rsonalization.md => 11-personalization.md} | 4 +- ...oubleshooting.md => 12-troubleshooting.md} | 4 +- ...is-manual.md => 13-viewing-this-manual.md} | 4 +- docs/verify-manual.py | 16 +- 23 files changed, 634 insertions(+), 603 deletions(-) delete mode 100644 docs/manual/07-customization.md create mode 100644 docs/manual/07-customization/01-machine-local-configuration.md create mode 100644 docs/manual/07-customization/02-secrets-and-api-keys.md create mode 100644 docs/manual/07-customization/03-overriding-configuration-variables.md create mode 100644 docs/manual/07-customization/04-fish-universal-variables.md create mode 100644 docs/manual/07-customization/05-opinionated-components-minimal-mode.md create mode 100644 docs/manual/07-customization/06-prompt-and-theme.md create mode 100644 docs/manual/07-customization/index.md create mode 100644 docs/manual/08-components-reference/01-c1-command-shadows.md create mode 100644 docs/manual/08-components-reference/02-c2-startup-side-effects.md create mode 100644 docs/manual/08-components-reference/03-c3-key-and-environment-overrides.md create mode 100644 docs/manual/08-components-reference/04-c4-terminal-and-tool-integration.md create mode 100644 docs/manual/08-components-reference/05-c5-logging-and-capture.md create mode 100644 docs/manual/08-components-reference/06-c6-greeting-and-first-run-ui.md create mode 100644 docs/manual/08-components-reference/index.md rename docs/manual/{08-fisher-plugins.md => 09-fisher-plugins.md} (99%) rename docs/manual/{09-installation.md => 10-installation.md} (97%) rename docs/manual/{10-personalization.md => 11-personalization.md} (98%) rename docs/manual/{11-troubleshooting.md => 12-troubleshooting.md} (99%) rename docs/manual/{12-viewing-this-manual.md => 13-viewing-this-manual.md} (98%) diff --git a/docs/fish-config.index b/docs/fish-config.index index af2a5fc..51fffd9 100644 --- a/docs/fish-config.index +++ b/docs/fish-config.index @@ -229,42 +229,42 @@ 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 -zellij=#### C5 — Logging and Capture -zellij-logging=#### C5 — Logging and Capture -tmux-logging=#### C5 — Logging and Capture -pipe-pane=#### C5 — Logging and Capture -dump-screen=#### C5 — Logging and Capture -c6=#### C6 — Greeting and First-Run UI -greeting=#### C6 — Greeting and First-Run UI +component-reference=# 8. COMPONENTS REFERENCE +components=# 8. COMPONENTS 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 +zellij=## C5 — Logging and Capture +zellij-logging=## C5 — Logging and Capture +tmux-logging=## C5 — Logging and Capture +pipe-pane=## C5 — Logging and Capture +dump-screen=## C5 — Logging and Capture +c6=## C6 — Greeting and First-Run UI +greeting=## C6 — Greeting and First-Run UI # ── Prompt and Theme ────────────────────────────────────────── prompt-theme=## Prompt and Theme -starship=### Starship -fallback-prompt=### Catppuccin Fallback Prompt -catppuccin-prompt=### Catppuccin Fallback Prompt -nim-prompt=### Catppuccin Fallback Prompt -fzf-theme=### FZF -catppuccin-theme=### Catppuccin Mocha Syntax Highlighting +starship=#### Starship +fallback-prompt=#### Catppuccin Fallback Prompt +catppuccin-prompt=#### Catppuccin Fallback Prompt +nim-prompt=#### Catppuccin Fallback Prompt +fzf-theme=#### FZF +catppuccin-theme=#### Catppuccin Mocha Syntax Highlighting -# ── Section 8: Fisher Plugins ───────────────────────────────── -plugins=# 8. FISHER PLUGINS -fisher=# 8. FISHER PLUGINS +# ── Section 9: Fisher Plugins ───────────────────────────────── +plugins=# 9. FISHER PLUGINS +fisher=# 9. FISHER PLUGINS fisher-managed=## Fisher-Managed Plugins sponge=## Fisher-Managed Plugins sponge-filtering=## Sponge History Filtering @@ -276,22 +276,22 @@ sponge-settings=### config-settings bundled-plugins=## Bundled Plugin Functionality fish-plugins-manifest=## fish_plugins Manifest -# ── Section 9: Installation ──────────────────────────────────── -installation=# 9. INSTALLATION -install=# 9. INSTALLATION +# ── Section 10: Installation ──────────────────────────────────── +installation=# 10. INSTALLATION +install=# 10. INSTALLATION sentinel=## Return Sentinel updating=## Updating -# ── Section 10: Personalization ─────────────────────────────── -personalization=# 10. PERSONALIZATION -personalize=# 10. PERSONALIZATION +# ── Section 11: Personalization ─────────────────────────────── +personalization=# 11. PERSONALIZATION +personalize=# 11. PERSONALIZATION secrets-file=## secrets.fish local-config=## local.fish -# ── Section 11: Troubleshooting ────────────────────────────── -troubleshooting=# 11. TROUBLESHOOTING -troubleshoot=# 11. TROUBLESHOOTING -faq=# 11. TROUBLESHOOTING +# ── Section 12: Troubleshooting ────────────────────────────── +troubleshooting=# 12. TROUBLESHOOTING +troubleshoot=# 12. TROUBLESHOOTING +faq=# 12. TROUBLESHOOTING uninstall=## Uninstalling and Reverting to Backup revert=## Uninstalling and Reverting to Backup fish-version=## Fish Version Requirement @@ -310,9 +310,9 @@ vi-trouble=## Vi Mode Keybindings emacs-mode=## Vi Mode Keybindings minimal-trouble=## What's with the C1-C6 stuff? -# ── Section 12: Viewing This Manual ────────────────────────── -viewing=# 12. VIEWING THIS MANUAL -manual=# 12. VIEWING THIS MANUAL +# ── Section 13: Viewing This Manual ────────────────────────── +viewing=# 13. VIEWING THIS MANUAL +manual=# 13. VIEWING THIS MANUAL ov=## In the terminal man-page=## As a man page manpage=## As a man page diff --git a/docs/fish-config.md b/docs/fish-config.md index b3d7419..8fae489 100644 --- a/docs/fish-config.md +++ b/docs/fish-config.md @@ -2768,13 +2768,78 @@ NOTE: - Disabled integration commands (spwin, tab, split, hist, logs, upgrade) print an error naming the variable that disabled them. - On CachyOS, the distro fish config's own aliases, history override, and bang-bang bindings are stripped per category as well. -### Component Reference +## Prompt and Theme + +#### Starship + +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. + +#### Catppuccin Fallback Prompt + +When Starship is absent or C3 overrides are disabled, a built-in nim-style +two-line prompt activates from functions/fish_prompt.fish. No external +dependencies — fish builtins only. + +Layout: + + ┬─[user@host:~/path] (main) + ╰─>$ + +Elements: + + user Yellow (Catppuccin Yellow); red if root + @host Blue (local) or Teal (SSH) + ~/path prompt_pwd abbreviation (Catppuccin Text) + (main) Current git branch in Catppuccin Pink; omitted outside repos + ─[V:name] Active Python venv basename; omitted when none + ─[N/I/R/V] Vi-mode indicator when vi bindings are active + ┬─ / ╰─> Connector lines: Catppuccin Green on success, Red on failure + +The right prompt (fish_right_prompt.fish) always renders, regardless of C3 +state. On failure it shows a red ✘ and the exit code; on success it shows +only the dim timestamp. When starship is installed and C3 is enabled, the +active Docker context is also shown (if non-default): + + ✘ 1 󰡨 myctx Fri Jun 12 00:51:21 2026 ← failed, starship+C3 active + ✘ 1 Fri Jun 12 00:51:21 2026 ← failed, fallback prompt + Fri Jun 12 00:51:21 2026 ← success (no ✘) + +#### FZF + +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. + +#### Catppuccin Mocha Syntax Highlighting + +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" + +--- + +# 8. COMPONENTS 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 +## C1 — Command Shadows Disabling __fish_config_op_aliases restores standard system behavior for all of these commands. @@ -2805,7 +2870,7 @@ all of these commands. 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 +## C2 — Startup Side-Effects These run automatically without any user action. Disabling __fish_config_op_autoexec prevents all of them. @@ -2848,7 +2913,7 @@ branches, or repos without a remote. The handler fires once per repo entry (not on every sub-directory cd). The registry is machine-local at `$__fish_user_dots_path/auto-pull.list` (defaults to `~/.config/.user-dots/fish/auto-pull.list`) and is never committed. -#### C3 — Key and Environment Overrides +## 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 @@ -2880,7 +2945,7 @@ 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 +## C4 — Terminal and Tool Integration These features couple the shell to specific external tools. Disabling __fish_config_op_integrations disables all of them. @@ -2902,7 +2967,7 @@ 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 +## C5 — Logging and Capture Five components capture shell output to disk. Unlike every other category, C5 is opt-in: it stays off until __fish_config_op_logging is set to an @@ -3012,7 +3077,7 @@ 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 +## C6 — Greeting and First-Run UI Component What it shows ─────────────────────────────────────────────────────────────────────────── @@ -3025,72 +3090,7 @@ 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 - -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. - -### Catppuccin Fallback Prompt - -When Starship is absent or C3 overrides are disabled, a built-in nim-style -two-line prompt activates from functions/fish_prompt.fish. No external -dependencies — fish builtins only. - -Layout: - - ┬─[user@host:~/path] (main) - ╰─>$ - -Elements: - - user Yellow (Catppuccin Yellow); red if root - @host Blue (local) or Teal (SSH) - ~/path prompt_pwd abbreviation (Catppuccin Text) - (main) Current git branch in Catppuccin Pink; omitted outside repos - ─[V:name] Active Python venv basename; omitted when none - ─[N/I/R/V] Vi-mode indicator when vi bindings are active - ┬─ / ╰─> Connector lines: Catppuccin Green on success, Red on failure - -The right prompt (fish_right_prompt.fish) always renders, regardless of C3 -state. On failure it shows a red ✘ and the exit code; on success it shows -only the dim timestamp. When starship is installed and C3 is enabled, the -active Docker context is also shown (if non-default): - - ✘ 1 󰡨 myctx Fri Jun 12 00:51:21 2026 ← failed, starship+C3 active - ✘ 1 Fri Jun 12 00:51:21 2026 ← failed, fallback prompt - Fri Jun 12 00:51:21 2026 ← success (no ✘) - -### FZF - -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. - -### Catppuccin Mocha Syntax Highlighting - -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" - ---- - -# 8. FISHER PLUGINS +# 9. FISHER PLUGINS Fisher is bootstrapped automatically on the **first interactive session** via `conf.d/first_run.fish`. This also applies the Catppuccin Mocha theme and @@ -3190,7 +3190,7 @@ update` which calls it as its first step. --- -# 9. INSTALLATION +# 10. INSTALLATION This configuration is managed as a git repository. To deploy on a new machine: @@ -3224,7 +3224,7 @@ All git output is suppressed. Run exec fish after a successful update to reload. --- -# 10. PERSONALIZATION +# 11. PERSONALIZATION Sensitive credentials and machine-specific settings are kept out of version control in a private directory. The path defaults to @@ -3286,7 +3286,7 @@ local.fish in turn sources secrets.fish when it exists. --- -# 11. TROUBLESHOOTING +# 12. TROUBLESHOOTING This section covers common issues, their solutions, and how to safely revert changes or uninstall the configuration entirely. @@ -3517,7 +3517,7 @@ For an interactive alternative to setting these variables by hand, run `config-s --- -# 12. VIEWING THIS MANUAL +# 13. VIEWING THIS MANUAL There are four ways to read this manual. diff --git a/docs/manual/07-customization.md b/docs/manual/07-customization.md deleted file mode 100644 index 440a6e3..0000000 --- a/docs/manual/07-customization.md +++ /dev/null @@ -1,463 +0,0 @@ ---- -title: Customization -manTitle: 7. CUSTOMIZATION -sidebar: - order: 11 -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 - -Place machine-specific settings that should not be committed to git in: - - $__fish_user_dots_path/local.fish - -`__fish_user_dots_path` defaults to `~/.config/.user-dots/fish`. Set a -custom location with: - - set -U __fish_user_dots_path /path/to/your/dots/fish - -Typical uses: additional PATH entries, local aliases, hostname-specific env -vars, work-specific tool configs. - -For convenience, a git-ignored `user-dots` symlink in the fish config -directory tracks `$__fish_user_dots_path` so the overlay can be browsed from -`~/.config/fish/`. It is created if missing and repointed if the path changes. -Opt out by setting `__fish_user_dots_symlink` to a falsy value, or toggling -"Dots link" off on the config-settings Paths page — this stops generation and -removes any existing link. It only ever manages a symlink and never clobbers a -real file or directory at that path. - -## Secrets and API Keys - - $__fish_user_dots_path/secrets.fish - -Store API tokens, GPG keys, private credentials here. This file is never -committed. It is sourced by local.fish directly, not by config.fish. - -`local.fish` is sourced at the end of config.fish on every interactive -session, so it and its companion secrets.fish can override anything set -earlier. - -## Overriding Configuration Variables - -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 200 - -## Fish Universal Variables - -Some settings (fzf colors, theme) are stored in fish_variables via -`set -U`. These are machine-local and git-ignored. Do not commit -fish_variables. - -## Opinionated Components (Minimal Mode) - -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 — except for C5 logging, which -is opt-in (see below). - -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. - -C5 (logging) is the one exception to "unset means enabled". Because it -writes terminal output to disk, it is opt-in: unset means disabled, and the -master switch cannot enable it. Only an explicit truthy value turns logging -on. - - 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, claude - AGENTS.md auto-link - __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 (OPT-IN — this one - is off unless explicitly enabled): - 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.fish - -Examples: - - # Disable command shadows only (rm becomes plain rm again): - set -U __fish_config_op_aliases off - - # Turn session logging on (opt-in; off until you do this): - set -U __fish_config_op_logging on - - # Full minimal mode — disable all six categories at once: - set -U __fish_config_opinionated 0 - - # Re-enable everything (except C5 logging, which stays opt-in): - 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) - -For an interactive alternative to setting these variables by hand, run -config-settings — a full-screen TUI that flips any category (including C5 -logging) on or off, per session or universally. See its entry in Section 5. - -NOTE: - - Command shadows (rm, cat, ls, ...) react immediately; conf.d-level components (bindings, prompt, abbreviations, hooks) take effect in new shells. - - With aliases disabled, rm falls back to bare `command rm` — files are deleted permanently, not trashed. - - Disabled integration commands (spwin, tab, split, hist, logs, upgrade) print an error naming the variable that disabled them. - - 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 - claude auto-links AGENTS.md as CLAUDE.md before launch command claude - edit multi-editor launcher (GUI/term + fallbacks) $EDITOR/nvim/nano/vi - -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 - Auto-pull fast-forward On entering a repo Background ff-only git pull - user-dots symlink Every startup Links $__fish_config_dir/user-dots - to $__fish_user_dots_path - -When C2 is disabled: no Fisher install, no theme application, no paru/yay -wrapper generation, no automatic venv activation, no WakaTime reporting, -no auto-pull (the PWD handler is never registered), and the user-dots -convenience symlink is not created. The symlink is git-ignored and only ever -managed as a symlink — a real file or directory at that path is left untouched. -The symlink has its own opt-out independent of C2: set __fish_user_dots_symlink -to a falsy value (or toggle "Dots link" off on the config-settings Paths page) -to stop generating it and remove any existing link — honoured even when C2 is -enabled. Managed by the __fish_user_dots_link helper. -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. - -Auto-pull fast-forwards opted-in repositories in the background when you cd -into them. The fish-config repo is always covered; other repos are added with -the `auto-pull` command (see its entry in the functions reference). It only -ever fast-forwards a clean repo whose branch has an upstream — never rebases, -merges, or overwrites work — so it is a no-op on dirty trees, divergent -branches, or repos without a remote. The handler fires once per repo entry -(not on every sub-directory cd). The registry is machine-local at -`$__fish_user_dots_path/auto-pull.list` (defaults to `~/.config/.user-dots/fish/auto-pull.list`) and is never committed. - -#### 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 - XDG variables Sets global XDG Base Directory variables - PATH setup Prepends custom bin directories to the PATH - 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: exit code (on failure) + dim timestamp; always rendered; Docker context added when starship+C3 active - -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 - -Five components capture shell output to disk. Unlike every other category, -C5 is opt-in: it stays off until __fish_config_op_logging is set to an -explicit truthy value, and a truthy master switch does not enable it. While -it is off, all capture is skipped and the logging wrappers are removed. - - # Turn it on (persistently, in every shell): - set -U __fish_config_op_logging on - - # Turn it back off: - set -U __fish_config_op_logging off # or: set -Ue __fish_config_op_logging - - Component What it captures - ─────────────────────────────────────────────────────────────────────────── - Scrollback capture Terminal session output saved to: - ~/.terminal_history/scrollback_YYYY-MM-DD_HH-MM-SS.log - tmux pane capture Continuous pane stream via pipe-pane, saved to: - ~/.terminal_history/tmux_-w-p_YYYY-MM-DD_HH-MM-SS.log - zellij pane capture Pane scrollback snapshot on shell exit, saved to: - ~/.terminal_history/zellij_-p_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 closes - -NOTE: **Turning off logging does not delete any existing logs.** -They remain in `$SCROLLBACK_HISTORY_DIR` (defaults to: `~/.terminal_history/`) -until you remove them manually. - -The tmux capture starts automatically when fish launches inside any tmux -pane ($TMUX is set). It uses tmux's native pipe-pane to stream all pane -output directly to disk without an intermediate process. Each fish shell -session gets its own log file; a new log is created on each shell start -(including exec fish and new splits). Before each new log, the oldest -tmux_*.log files are pruned (by modification time) to keep the total within -SCROLLBACK_HISTORY_MAX_FILES, matching the paru/yay wrapper behaviour. - -The zellij capture works differently: Zellij has no live output-streaming -facility like pipe-pane, so the log is taken as a one-shot snapshot when the -shell exits, via `zellij action dump-screen --full --ansi` (the --ansi flag -preserves color). The dump is captured on the fish process's stdout and -written to the log file by fish itself (not via `--path`, which would make the -zellij server write the file). A fish_exit handler (registered whenever -$ZELLIJ is set) writes the pane's full scrollback and then prunes old -zellij_*.log files the same way. Because the capture happens at exit, toggling -__fish_config_op_logging takes effect on the next exit with no restart or -sentinel coordination needed — the C5 guard is re-checked when the handler -fires. - -LIMITATION — zellij capture only fires on a clean shell exit (typing `exit`, -Ctrl-D, or a logout), because that is when the fish_exit handler runs. It does -NOT capture when you close a pane or quit zellij through zellij itself: - - - Closing a pane signals the shell and tears the pane down concurrently, so - even if the handler runs, `dump-screen` may find the pane buffer already - gone. - - Quitting zellij kills the zellij server, and `dump-screen` needs a live - server to read from — there is nothing left to snapshot. - -This is a structural difference from tmux, NOT a bug. tmux streams pane output -to disk continuously via pipe-pane, so whatever was printed is already saved -no matter how the pane dies. Zellij can only snapshot, and the only reliable -snapshot point from the shell is a clean exit. To guarantee a zellij pane is -logged, end the session with `exit` or Ctrl-D rather than zellij's close-pane -or quit actions. - -The Kitty watcher is managed by the kitty-logging command: it symlinks the -watcher (fish-config-watcher.py) into the Kitty config directory and wires it -into kitty.conf via a managed block. Inside Kitty, a non-blocking -per-session reminder points first-time users at `kitty-logging install` until -they install or run `kitty-logging dismiss`; the reminder is itself gated on -C5, so it stays silent until you enable logging. Install affects new Kitty -windows only; runtime disable is still handled by the .logging_disabled -sentinel. - -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 - -Because C5 is off by default, the sentinel is present on a fresh install — -the startup sync in conf.d/logging-events.fish reconciles it on every shell -start, so it appears without any action on your part. - -Disabling __fish_config_op_logging (or leaving it unset): - 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. - 5. Stops tmux pipe-pane capture in every open fish shell inside tmux. - -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. - 4. Restarts tmux pipe-pane capture in every open fish shell inside tmux. - -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 - -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. - -### Catppuccin Fallback Prompt - -When Starship is absent or C3 overrides are disabled, a built-in nim-style -two-line prompt activates from functions/fish_prompt.fish. No external -dependencies — fish builtins only. - -Layout: - - ┬─[user@host:~/path] (main) - ╰─>$ - -Elements: - - user Yellow (Catppuccin Yellow); red if root - @host Blue (local) or Teal (SSH) - ~/path prompt_pwd abbreviation (Catppuccin Text) - (main) Current git branch in Catppuccin Pink; omitted outside repos - ─[V:name] Active Python venv basename; omitted when none - ─[N/I/R/V] Vi-mode indicator when vi bindings are active - ┬─ / ╰─> Connector lines: Catppuccin Green on success, Red on failure - -The right prompt (fish_right_prompt.fish) always renders, regardless of C3 -state. On failure it shows a red ✘ and the exit code; on success it shows -only the dim timestamp. When starship is installed and C3 is enabled, the -active Docker context is also shown (if non-default): - - ✘ 1 󰡨 myctx Fri Jun 12 00:51:21 2026 ← failed, starship+C3 active - ✘ 1 Fri Jun 12 00:51:21 2026 ← failed, fallback prompt - Fri Jun 12 00:51:21 2026 ← success (no ✘) - -### FZF - -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. - -### Catppuccin Mocha Syntax Highlighting - -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" - ---- diff --git a/docs/manual/07-customization/01-machine-local-configuration.md b/docs/manual/07-customization/01-machine-local-configuration.md new file mode 100644 index 0000000..f3abeb7 --- /dev/null +++ b/docs/manual/07-customization/01-machine-local-configuration.md @@ -0,0 +1,24 @@ +--- +title: Machine-local Configuration +--- + +Place machine-specific settings that should not be committed to git in: + + $__fish_user_dots_path/local.fish + +`__fish_user_dots_path` defaults to `~/.config/.user-dots/fish`. Set a +custom location with: + + set -U __fish_user_dots_path /path/to/your/dots/fish + +Typical uses: additional PATH entries, local aliases, hostname-specific env +vars, work-specific tool configs. + +For convenience, a git-ignored `user-dots` symlink in the fish config +directory tracks `$__fish_user_dots_path` so the overlay can be browsed from +`~/.config/fish/`. It is created if missing and repointed if the path changes. +Opt out by setting `__fish_user_dots_symlink` to a falsy value, or toggling +"Dots link" off on the config-settings Paths page — this stops generation and +removes any existing link. It only ever manages a symlink and never clobbers a +real file or directory at that path. + diff --git a/docs/manual/07-customization/02-secrets-and-api-keys.md b/docs/manual/07-customization/02-secrets-and-api-keys.md new file mode 100644 index 0000000..48f7d1d --- /dev/null +++ b/docs/manual/07-customization/02-secrets-and-api-keys.md @@ -0,0 +1,13 @@ +--- +title: Secrets and API Keys +--- + + $__fish_user_dots_path/secrets.fish + +Store API tokens, GPG keys, private credentials here. This file is never +committed. It is sourced by local.fish directly, not by config.fish. + +`local.fish` is sourced at the end of config.fish on every interactive +session, so it and its companion secrets.fish can override anything set +earlier. + diff --git a/docs/manual/07-customization/03-overriding-configuration-variables.md b/docs/manual/07-customization/03-overriding-configuration-variables.md new file mode 100644 index 0000000..f9fd8d7 --- /dev/null +++ b/docs/manual/07-customization/03-overriding-configuration-variables.md @@ -0,0 +1,10 @@ +--- +title: Overriding Configuration Variables +--- + +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 200 + diff --git a/docs/manual/07-customization/04-fish-universal-variables.md b/docs/manual/07-customization/04-fish-universal-variables.md new file mode 100644 index 0000000..93c62af --- /dev/null +++ b/docs/manual/07-customization/04-fish-universal-variables.md @@ -0,0 +1,8 @@ +--- +title: Fish Universal Variables +--- + +Some settings (fzf colors, theme) are stored in fish_variables via +`set -U`. These are machine-local and git-ignored. Do not commit +fish_variables. + diff --git a/docs/manual/07-customization/05-opinionated-components-minimal-mode.md b/docs/manual/07-customization/05-opinionated-components-minimal-mode.md new file mode 100644 index 0000000..56fd040 --- /dev/null +++ b/docs/manual/07-customization/05-opinionated-components-minimal-mode.md @@ -0,0 +1,86 @@ +--- +title: Opinionated Components (Minimal Mode) +--- + +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 — except for C5 logging, which +is opt-in (see below). + +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. + +C5 (logging) is the one exception to "unset means enabled". Because it +writes terminal output to disk, it is opt-in: unset means disabled, and the +master switch cannot enable it. Only an explicit truthy value turns logging +on. + + 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, claude + AGENTS.md auto-link + __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 (OPT-IN — this one + is off unless explicitly enabled): + 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.fish + +Examples: + + # Disable command shadows only (rm becomes plain rm again): + set -U __fish_config_op_aliases off + + # Turn session logging on (opt-in; off until you do this): + set -U __fish_config_op_logging on + + # Full minimal mode — disable all six categories at once: + set -U __fish_config_opinionated 0 + + # Re-enable everything (except C5 logging, which stays opt-in): + 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) + +For an interactive alternative to setting these variables by hand, run +config-settings — a full-screen TUI that flips any category (including C5 +logging) on or off, per session or universally. See its entry in Section 5. + +NOTE: + - Command shadows (rm, cat, ls, ...) react immediately; conf.d-level components (bindings, prompt, abbreviations, hooks) take effect in new shells. + - With aliases disabled, rm falls back to bare `command rm` — files are deleted permanently, not trashed. + - Disabled integration commands (spwin, tab, split, hist, logs, upgrade) print an error naming the variable that disabled them. + - On CachyOS, the distro fish config's own aliases, history override, and bang-bang bindings are stripped per category as well. + diff --git a/docs/manual/07-customization/06-prompt-and-theme.md b/docs/manual/07-customization/06-prompt-and-theme.md new file mode 100644 index 0000000..d573567 --- /dev/null +++ b/docs/manual/07-customization/06-prompt-and-theme.md @@ -0,0 +1,66 @@ +--- +title: Prompt and Theme +--- + +### Starship + +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. + +### Catppuccin Fallback Prompt + +When Starship is absent or C3 overrides are disabled, a built-in nim-style +two-line prompt activates from functions/fish_prompt.fish. No external +dependencies — fish builtins only. + +Layout: + + ┬─[user@host:~/path] (main) + ╰─>$ + +Elements: + + user Yellow (Catppuccin Yellow); red if root + @host Blue (local) or Teal (SSH) + ~/path prompt_pwd abbreviation (Catppuccin Text) + (main) Current git branch in Catppuccin Pink; omitted outside repos + ─[V:name] Active Python venv basename; omitted when none + ─[N/I/R/V] Vi-mode indicator when vi bindings are active + ┬─ / ╰─> Connector lines: Catppuccin Green on success, Red on failure + +The right prompt (fish_right_prompt.fish) always renders, regardless of C3 +state. On failure it shows a red ✘ and the exit code; on success it shows +only the dim timestamp. When starship is installed and C3 is enabled, the +active Docker context is also shown (if non-default): + + ✘ 1 󰡨 myctx Fri Jun 12 00:51:21 2026 ← failed, starship+C3 active + ✘ 1 Fri Jun 12 00:51:21 2026 ← failed, fallback prompt + Fri Jun 12 00:51:21 2026 ← success (no ✘) + +### FZF + +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. + +### Catppuccin Mocha Syntax Highlighting + +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" + +--- diff --git a/docs/manual/07-customization/index.md b/docs/manual/07-customization/index.md new file mode 100644 index 0000000..888d130 --- /dev/null +++ b/docs/manual/07-customization/index.md @@ -0,0 +1,11 @@ +--- +title: Customization +manTitle: 7. CUSTOMIZATION +sidebar: + order: 11 +helpKeywords: +- customization +- customize +--- +This section explains how to adapt the configuration to your specific workflow, including local machine overrides and opinionated component toggles. + diff --git a/docs/manual/08-components-reference/01-c1-command-shadows.md b/docs/manual/08-components-reference/01-c1-command-shadows.md new file mode 100644 index 0000000..116c960 --- /dev/null +++ b/docs/manual/08-components-reference/01-c1-command-shadows.md @@ -0,0 +1,33 @@ +--- +title: 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 + claude auto-links AGENTS.md as CLAUDE.md before launch command claude + edit multi-editor launcher (GUI/term + fallbacks) $EDITOR/nvim/nano/vi + +When C1 is disabled, `rm` uses bare `command rm` with no wrapper — files +are permanently deleted, not trashed. There is no intermediate safety net. + diff --git a/docs/manual/08-components-reference/02-c2-startup-side-effects.md b/docs/manual/08-components-reference/02-c2-startup-side-effects.md new file mode 100644 index 0000000..f0be19c --- /dev/null +++ b/docs/manual/08-components-reference/02-c2-startup-side-effects.md @@ -0,0 +1,45 @@ +--- +title: 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 + Auto-pull fast-forward On entering a repo Background ff-only git pull + user-dots symlink Every startup Links $__fish_config_dir/user-dots + to $__fish_user_dots_path + +When C2 is disabled: no Fisher install, no theme application, no paru/yay +wrapper generation, no automatic venv activation, no WakaTime reporting, +no auto-pull (the PWD handler is never registered), and the user-dots +convenience symlink is not created. The symlink is git-ignored and only ever +managed as a symlink — a real file or directory at that path is left untouched. +The symlink has its own opt-out independent of C2: set __fish_user_dots_symlink +to a falsy value (or toggle "Dots link" off on the config-settings Paths page) +to stop generating it and remove any existing link — honoured even when C2 is +enabled. Managed by the __fish_user_dots_link helper. +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. + +Auto-pull fast-forwards opted-in repositories in the background when you cd +into them. The fish-config repo is always covered; other repos are added with +the `auto-pull` command (see its entry in the functions reference). It only +ever fast-forwards a clean repo whose branch has an upstream — never rebases, +merges, or overwrites work — so it is a no-op on dirty trees, divergent +branches, or repos without a remote. The handler fires once per repo entry +(not on every sub-directory cd). The registry is machine-local at +`$__fish_user_dots_path/auto-pull.list` (defaults to `~/.config/.user-dots/fish/auto-pull.list`) and is never committed. + diff --git a/docs/manual/08-components-reference/03-c3-key-and-environment-overrides.md b/docs/manual/08-components-reference/03-c3-key-and-environment-overrides.md new file mode 100644 index 0000000..06c6459 --- /dev/null +++ b/docs/manual/08-components-reference/03-c3-key-and-environment-overrides.md @@ -0,0 +1,35 @@ +--- +title: 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 + PATH setup Prepends custom bin directories to the PATH + exit → smart_exit exit wrapper that captures scrollback before closing + PAGER=ov ov used by git, man, and all $PAGER-aware tools + EDITOR=nvim nvim fallback to vi for git commit, etc. + GPG_TTY Sets GPG_TTY to current terminal tty + 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: exit code (on failure) + dim timestamp; always rendered; Docker context added when starship+C3 active + +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). + diff --git a/docs/manual/08-components-reference/04-c4-terminal-and-tool-integration.md b/docs/manual/08-components-reference/04-c4-terminal-and-tool-integration.md new file mode 100644 index 0000000..101b0e1 --- /dev/null +++ b/docs/manual/08-components-reference/04-c4-terminal-and-tool-integration.md @@ -0,0 +1,24 @@ +--- +title: 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. + diff --git a/docs/manual/08-components-reference/05-c5-logging-and-capture.md b/docs/manual/08-components-reference/05-c5-logging-and-capture.md new file mode 100644 index 0000000..0fceb7e --- /dev/null +++ b/docs/manual/08-components-reference/05-c5-logging-and-capture.md @@ -0,0 +1,112 @@ +--- +title: C5 — Logging and Capture +--- + +Five components capture shell output to disk. Unlike every other category, +C5 is opt-in: it stays off until __fish_config_op_logging is set to an +explicit truthy value, and a truthy master switch does not enable it. While +it is off, all capture is skipped and the logging wrappers are removed. + + # Turn it on (persistently, in every shell): + set -U __fish_config_op_logging on + + # Turn it back off: + set -U __fish_config_op_logging off # or: set -Ue __fish_config_op_logging + + Component What it captures + ─────────────────────────────────────────────────────────────────────────── + Scrollback capture Terminal session output saved to: + ~/.terminal_history/scrollback_YYYY-MM-DD_HH-MM-SS.log + tmux pane capture Continuous pane stream via pipe-pane, saved to: + ~/.terminal_history/tmux_-w-p_YYYY-MM-DD_HH-MM-SS.log + zellij pane capture Pane scrollback snapshot on shell exit, saved to: + ~/.terminal_history/zellij_-p_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 closes + +NOTE: **Turning off logging does not delete any existing logs.** +They remain in `$SCROLLBACK_HISTORY_DIR` (defaults to: `~/.terminal_history/`) +until you remove them manually. + +The tmux capture starts automatically when fish launches inside any tmux +pane ($TMUX is set). It uses tmux's native pipe-pane to stream all pane +output directly to disk without an intermediate process. Each fish shell +session gets its own log file; a new log is created on each shell start +(including exec fish and new splits). Before each new log, the oldest +tmux_*.log files are pruned (by modification time) to keep the total within +SCROLLBACK_HISTORY_MAX_FILES, matching the paru/yay wrapper behaviour. + +The zellij capture works differently: Zellij has no live output-streaming +facility like pipe-pane, so the log is taken as a one-shot snapshot when the +shell exits, via `zellij action dump-screen --full --ansi` (the --ansi flag +preserves color). The dump is captured on the fish process's stdout and +written to the log file by fish itself (not via `--path`, which would make the +zellij server write the file). A fish_exit handler (registered whenever +$ZELLIJ is set) writes the pane's full scrollback and then prunes old +zellij_*.log files the same way. Because the capture happens at exit, toggling +__fish_config_op_logging takes effect on the next exit with no restart or +sentinel coordination needed — the C5 guard is re-checked when the handler +fires. + +LIMITATION — zellij capture only fires on a clean shell exit (typing `exit`, +Ctrl-D, or a logout), because that is when the fish_exit handler runs. It does +NOT capture when you close a pane or quit zellij through zellij itself: + + - Closing a pane signals the shell and tears the pane down concurrently, so + even if the handler runs, `dump-screen` may find the pane buffer already + gone. + - Quitting zellij kills the zellij server, and `dump-screen` needs a live + server to read from — there is nothing left to snapshot. + +This is a structural difference from tmux, NOT a bug. tmux streams pane output +to disk continuously via pipe-pane, so whatever was printed is already saved +no matter how the pane dies. Zellij can only snapshot, and the only reliable +snapshot point from the shell is a clean exit. To guarantee a zellij pane is +logged, end the session with `exit` or Ctrl-D rather than zellij's close-pane +or quit actions. + +The Kitty watcher is managed by the kitty-logging command: it symlinks the +watcher (fish-config-watcher.py) into the Kitty config directory and wires it +into kitty.conf via a managed block. Inside Kitty, a non-blocking +per-session reminder points first-time users at `kitty-logging install` until +they install or run `kitty-logging dismiss`; the reminder is itself gated on +C5, so it stays silent until you enable logging. Install affects new Kitty +windows only; runtime disable is still handled by the .logging_disabled +sentinel. + +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 + +Because C5 is off by default, the sentinel is present on a fresh install — +the startup sync in conf.d/logging-events.fish reconciles it on every shell +start, so it appears without any action on your part. + +Disabling __fish_config_op_logging (or leaving it unset): + 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. + 5. Stops tmux pipe-pane capture in every open fish shell inside tmux. + +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. + 4. Restarts tmux pipe-pane capture in every open fish shell inside tmux. + +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. + diff --git a/docs/manual/08-components-reference/06-c6-greeting-and-first-run-ui.md b/docs/manual/08-components-reference/06-c6-greeting-and-first-run-ui.md new file mode 100644 index 0000000..699e721 --- /dev/null +++ b/docs/manual/08-components-reference/06-c6-greeting-and-first-run-ui.md @@ -0,0 +1,15 @@ +--- +title: 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. + diff --git a/docs/manual/08-components-reference/index.md b/docs/manual/08-components-reference/index.md new file mode 100644 index 0000000..0db32c8 --- /dev/null +++ b/docs/manual/08-components-reference/index.md @@ -0,0 +1,12 @@ +--- +title: Components Reference +manTitle: 8. COMPONENTS REFERENCE +sidebar: + order: 12 +helpKeywords: +- componentsreference +--- +The following tables detail every component in each category. Use this +reference to understand exactly which behaviors change when you toggle a +category variable. + diff --git a/docs/manual/08-fisher-plugins.md b/docs/manual/09-fisher-plugins.md similarity index 99% rename from docs/manual/08-fisher-plugins.md rename to docs/manual/09-fisher-plugins.md index 685303d..2486717 100644 --- a/docs/manual/08-fisher-plugins.md +++ b/docs/manual/09-fisher-plugins.md @@ -1,8 +1,8 @@ --- title: Fisher Plugins -manTitle: 8. FISHER PLUGINS +manTitle: 9. FISHER PLUGINS sidebar: - order: 12 + order: 13 helpKeywords: - plugins - fisher diff --git a/docs/manual/09-installation.md b/docs/manual/10-installation.md similarity index 97% rename from docs/manual/09-installation.md rename to docs/manual/10-installation.md index 934ff92..5b22f10 100644 --- a/docs/manual/09-installation.md +++ b/docs/manual/10-installation.md @@ -1,8 +1,8 @@ --- title: Installation -manTitle: 9. INSTALLATION +manTitle: 10. INSTALLATION sidebar: - order: 13 + order: 14 helpKeywords: - installation - install diff --git a/docs/manual/10-personalization.md b/docs/manual/11-personalization.md similarity index 98% rename from docs/manual/10-personalization.md rename to docs/manual/11-personalization.md index 0e5e4c6..1d577d0 100644 --- a/docs/manual/10-personalization.md +++ b/docs/manual/11-personalization.md @@ -1,8 +1,8 @@ --- title: Personalization -manTitle: 10. PERSONALIZATION +manTitle: 11. PERSONALIZATION sidebar: - order: 14 + order: 15 helpKeywords: - personalization - personalize diff --git a/docs/manual/11-troubleshooting.md b/docs/manual/12-troubleshooting.md similarity index 99% rename from docs/manual/11-troubleshooting.md rename to docs/manual/12-troubleshooting.md index 3523954..d5a2abd 100644 --- a/docs/manual/11-troubleshooting.md +++ b/docs/manual/12-troubleshooting.md @@ -1,8 +1,8 @@ --- title: Troubleshooting -manTitle: 11. TROUBLESHOOTING +manTitle: 12. TROUBLESHOOTING sidebar: - order: 15 + order: 16 helpKeywords: - troubleshooting - troubleshoot diff --git a/docs/manual/12-viewing-this-manual.md b/docs/manual/13-viewing-this-manual.md similarity index 98% rename from docs/manual/12-viewing-this-manual.md rename to docs/manual/13-viewing-this-manual.md index 05cc80b..95f636c 100644 --- a/docs/manual/12-viewing-this-manual.md +++ b/docs/manual/13-viewing-this-manual.md @@ -1,8 +1,8 @@ --- title: Viewing This Manual -manTitle: 12. VIEWING THIS MANUAL +manTitle: 13. VIEWING THIS MANUAL sidebar: - order: 16 + order: 17 helpKeywords: - viewing - manual diff --git a/docs/verify-manual.py b/docs/verify-manual.py index afbb363..092bd39 100644 --- a/docs/verify-manual.py +++ b/docs/verify-manual.py @@ -687,10 +687,10 @@ def test_as_file_tree_accepts_deeper_trees(): def test_customization_notes_render_as_aside(): - """The real 07-customization.md NOTE paragraph converts to one intact