From 8ad10c41d7df4bc6dd19c81ef29ad1305b91b894 Mon Sep 17 00:00:00 2001 From: Gitea Actions Date: Mon, 8 Jun 2026 21:09:54 +0000 Subject: [PATCH] chore(docs): regenerate man page, HTML docs, and wiki --- docs/fish-config.1 | 339 ++++++++++- docs/html/10-6-dependency-catalog.html | 2 +- docs/html/11-7-customization.html | 25 + docs/html/12-8-fisher-plugins.html | 2 +- docs/html/13-9-installation.html | 520 +++++++++++++++++ docs/html/14-10-personalization.html | 532 ++++++++++++++++++ ...al.html => 15-11-viewing-this-manual.html} | 18 +- docs/html/3-description.html | 32 +- docs/html/4-table-of-contents.html | 5 +- docs/html/5-1-configuration-variables.html | 49 ++ docs/html/7-3-key-bindings.html | 13 +- docs/html/8-4-abbreviations.html | 30 + docs/html/index.html | 88 ++- docs/html/sitemap.json | 2 +- 14 files changed, 1605 insertions(+), 52 deletions(-) create mode 100644 docs/html/13-9-installation.html create mode 100644 docs/html/14-10-personalization.html rename docs/html/{13-9-viewing-this-manual.html => 15-11-viewing-this-manual.html} (96%) diff --git a/docs/fish-config.1 b/docs/fish-config.1 index f95c8da..e18c152 100644 --- a/docs/fish-config.1 +++ b/docs/fish-config.1 @@ -69,13 +69,31 @@ The configuration is split across: .IP .nf \f[C] -config.fish Main entry point; sets env vars and PATH -conf.d/ Auto-sourced fragments: keybindings, abbreviations, - theme, starship, zoxide, wakatime -functions/ One function per file, autoloaded by Fish -completions/ Tab completion scripts -integrations/ FZF Catppuccin theme and bindings -docs/ This offline documentation and compiled man page +config.fish Main entry point; sets env vars and PATH +conf.d/ + abbr.fish All abbreviations + cheat.fish cheat.sh completions + done.fish Desktop notifications for long commands + first_run.fish One-time init: Fisher bootstrap, theme, welcome + key_bindings.fish Custom key bindings and Vi mode + paru-wrapper.fish Auto-generates \[ti]/.local/bin/paru logging wrapper + starship.fish fish_prompt with OSC 133 shell-integration markers + tailscale.fish Tailscale CLI tab completions + theme.fish Catppuccin syntax highlight colors + tricks.fish PATH, bang-bang helpers, bat man pages, aliases + wakatime.fish WakaTime shell hook + yay-wrapper.fish Auto-generates \[ti]/.local/bin/yay logging wrapper + zoxide.fish Zoxide z/zi integration; overrides cd +functions/ Custom functions, one per file, autoloaded +completions/ Tab completion scripts +integrations/ + fzf.fish FZF Catppuccin theme and key binding config +docs/ Offline documentation and compiled man page + fish-config.md Primary source manual (terminal-readable) + fish-config.1 Compiled man page (auto-generated by CI) + fish-config.index Section index for help config navigation + html/ Chunked HTML docs (auto-generated by CI) + wiki/ Markdown wiki (auto-generated by CI) \f[R] .fi .PP @@ -98,6 +116,7 @@ docs/ This offline documentation and compiled man page 4.8 AI Assistants 4.9 History Expansion 4.10 Miscellaneous + 4.11 Shell Aliases 5. Functions Reference 5.1 File and Directory 5.2 Navigation @@ -116,7 +135,9 @@ docs/ This offline documentation and compiled man page 6. Dependency Catalog 7. Customization 8. Fisher Plugins -9. Viewing This Manual +9. Installation +10. Personalization +11. Viewing This Manual \f[R] .fi .PP @@ -185,6 +206,88 @@ CLAUDE_CODE_NO_FLICKER 1 \[em] suppress terminal flicker in Claude Code CDPATH . \[ti]/projects \[ti] \f[R] .fi +.SS Pager Hierarchy +.PP +$PAGER is set to ov when available, falling back to less. +The less wrapper function extends this into a full chain so anything +that calls less directly also benefits: +.IP +.nf +\f[C] +$PAGER → ov → less → more → cat +\f[R] +.fi +.PP +When bat is installed, man pages are rendered with syntax highlighting: +.IP +.nf +\f[C] +MANROFFOPT -c +MANPAGER sh -c \[aq]col -bx | bat -l man -p\[aq] +\f[R] +.fi +.SS Integrations +.SS Zoxide +.PP +cd, z, and cdi/zi are all mapped to zoxide-backed navigation. +Tab completions for cd and z blend standard directory entries (CWD and +CDPATH) with frecency results so both familiar and frequently-visited +paths appear in one list. +.SS DirEnv +.PP +Automatically loads .envrc files on directory change. +Takes priority over the auto-venv logic \[em] if a directory is managed +by direnv, the auto-venv activation is skipped entirely. +.SS Auto Python Venv +.PP +When entering a directory that contains a .venv/, the virtualenv is +activated automatically and deactivated when you leave the project tree. +.SS WakaTime +.PP +Every shell command is reported to WakaTime for time-tracking. +Set FISH_WAKATIME_DISABLED=1 to disable without removing the plugin. +.SS Tailscale +.PP +Full tab completion for the tailscale CLI is provided via +conf.d/tailscale.fish. +.SS Done Notifications +.PP +Desktop notifications fire when a command takes longer than 10 seconds +and the terminal window is not focused. +Configured via fish universal variables: +.IP +.nf +\f[C] +__done_min_cmd_duration 10000 ms +__done_notification_urgency_level low +\f[R] +.fi +.SS Scrollback History +.PP +When running inside Kitty, closing a shell session via exit saves a +timestamped scrollback snapshot to SCROLLBACK_HISTORY_DIR. +Files are named: +.IP +.nf +\f[C] +scrollback_YYYY-MM-DD_HH-MM-SS.log +\f[R] +.fi +.PP +The paru and yay wrappers (auto-generated in \[ti]/.local/bin/) tee all +output to: +.IP +.nf +\f[C] +paru_YYYY-MM-DD_HH-MM-SS.log +yay_YYYY-MM-DD_HH-MM-SS.log +\f[R] +.fi +.PP +Before pruning, _scrollback_prune_junk silently removes empty files, +files with only a single meaningful line (e.g.\ bare [exited] captures), +and Kitty tab-rename prompt captures. +Use exit \[en]no-log (or exit -n) to skip capture. .PP * * * * * .SH 2. PATH SETUP @@ -251,13 +354,16 @@ Ctrl+Enter Smart execute: runs commands instantly without at the cursor position. \f[R] .fi -.SS FZF Bindings (from fzf \[en]fish integration) +.SS FZF Bindings (from PatrickF1/fzf.fish) .IP .nf \f[C] -Ctrl+R Search shell history with fzf -Ctrl+T Insert a file path from fzf -Alt+C cd into a directory chosen with fzf +Ctrl+R Search command history +Ctrl+Alt+F Search git-tracked files +Ctrl+Alt+L Search git log +Ctrl+Alt+S Search git status +Ctrl+V Search shell variables +Ctrl+Alt+P Search running processes \f[R] .fi .PP @@ -442,6 +548,63 @@ bsh bd show lb lazybeads \f[R] .fi +.SS 4.11 Shell Aliases +.PP +These aliases are defined in conf.d/tricks.fish via alias (which creates +Fish functions). +They are active in all interactive sessions. +.SS Navigation +.IP +.nf +\f[C] +\&.. cd .. +\&... cd ../.. +\&.... cd ../../.. +\&..... cd ../../../.. +\&...... cd ../../../../.. +\f[R] +.fi +.SS Color Overrides +.PP +Force color output for common tools: +.IP +.nf +\f[C] +grep grep --color=auto +fgrep fgrep --color=auto +egrep egrep --color=auto +dir dir --color=auto +vdir vdir --color=auto +\f[R] +.fi +.SS Safety Wrappers +.PP +Add -i (interactive confirmation) to destructive commands: +.IP +.nf +\f[C] +cp cp -i +mv mv -i +\f[R] +.fi +.SS Archives and Networking +.IP +.nf +\f[C] +tarnow tar -acf Create compressed archive (auto-detects format) +untar tar -zxvf Extract a gzip-compressed archive +wget wget -c Resume interrupted downloads by default +tb nc termbin.com 9999 Pipe content to termbin.com for quick sharing +\f[R] +.fi +.SS System Logs +.IP +.nf +\f[C] +jctl journalctl -p 3 -xb Show priority-3 (error) journal entries + from the current boot +\f[R] +.fi .PP * * * * * .SH 5. FUNCTIONS REFERENCE @@ -1600,6 +1763,48 @@ Some settings (fzf colors, theme) are stored in fish_variables via \f[V]set -U\f[R]. These are machine-local and git-ignored. Do not commit fish_variables. +.SS Prompt and Theme +.SS Starship +.PP +The primary prompt is Starship, initialized by conf.d/starship.fish. +Configure it via \[ti]/.config/starship.toml. +.PP +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\[cq]s built-in prompt handles these markers +automatically. +.SS FZF +.PP +FZF is themed to Catppuccin Mocha via FZF_DEFAULT_OPTS set in +integrations/fzf.fish. +The colors applied: +.IP +.nf +\f[C] +Background: #1E1E2E (base) #313244 (surface0) +Foreground: #CDD6F4 (text) +Highlights: #F38BA8 (red) #CBA6F7 (mauve) #B4BEFE (lavender) +\f[R] +.fi +.PP +To customize, override FZF_DEFAULT_OPTS in local.fish. +.SS Catppuccin Mocha Syntax Highlighting +.PP +The catppuccin/fish plugin applies syntax highlight colors on first run. +Colors are stored in fish_variables (universal). +To switch variants, install a different theme from the themes/ +directory: +.IP +.nf +\f[C] +fish_config theme save \[dq]Catppuccin Latte\[dq] +\f[R] +.fi .PP * * * * * .SH 8. FISHER PLUGINS @@ -1639,7 +1844,115 @@ Run \f[V]fisher update\f[R] to update all plugins, or \f[V]fish-deps update\f[R] which calls fisher update as its first step. .PP * * * * * -.SH 9. VIEWING THIS MANUAL +.SH 9. INSTALLATION +.PP +This configuration is managed as a git repository. +To deploy on a new machine: +.IP +.nf +\f[C] +mv \[ti]/.config/fish \[ti]/.config/fish.bak # back up any existing config +git clone https://git.rootiest.dev/rootiest/fish-config.git \[ti]/.config/fish +\f[R] +.fi +.PP +Then open a new Fish shell. +Fisher and all plugins install automatically on first launch and the +Catppuccin Mocha theme is applied. +.SS Return Sentinel +.PP +config.fish ends with a return sentinel guard. +Any lines appended after it by a tool\[cq]s setup command (starship init +fish | source, zoxide init fish | source, etc.) +will have no effect. +All integrations are managed via conf.d/ files. +.PP +If a new tool\[cq]s shell integration appears to do nothing, check +whether its setup command appended an init line below the sentinel and +create a dedicated conf.d/.fish instead. +.SS Updating +.PP +Pull the latest changes from the upstream repository without needing a +configured git remote: +.IP +.nf +\f[C] +config-update Fetch and apply the latest commits from upstream +config-update --dry-run Preview available changes without applying them +config-update --force Stash local changes, pull, then restore the stash +\f[R] +.fi +.PP +The remote URL (https://git.rootiest.dev/rootiest/fish-config.git) is +hard-coded, so this works on a fresh clone with no origin configured. +All git output is suppressed. +Run exec fish after a successful update to reload. +.PP + * * * * * +.SH 10. PERSONALIZATION +.PP +Sensitive credentials and machine-specific settings are kept out of +version control in a private directory at +\[ti]/.config/.user-dots/fish/. +Two files are sourced automatically by config.fish if they exist: +.IP +.nf +\f[C] +\[ti]/.config/.user-dots/fish/ +├── secrets.fish API keys, tokens, passwords, personal identifiers +└── local.fish Machine-specific paths and environment variables +\f[R] +.fi +.PP +fish_variables (auto-managed by fish) is excluded from this repo via +\&.gitignore. +Do not commit it. +.SS secrets.fish +.PP +Store anything you would not commit to a public repo: API keys, auth +tokens, passwords, and personal identifiers. +.IP +.nf +\f[C] +set -gx MY_NAME \[dq]Your Name\[dq] +set -gx MY_EMAIL \[dq]you\[at]example.com\[dq] +set -gx GPG_RECIPIENT \[dq]you\[at]example.com\[dq] +set -gx GITHUB_TOKEN ghp_yourTokenHere +set -gx OPENAI_API_KEY sk-proj-yourKeyHere +set -gx GITEA_TOKEN yourGiteaTokenHere +set -gx GITEA_CHOSEN_LOGIN your.gitea.instance +set -gx KOPIA_PASSWORD yourKopiaPassword +\f[R] +.fi +.SS local.fish +.PP +Store paths and variables specific to one machine \[em] things that +would be wrong on any other system. +.IP +.nf +\f[C] +# CDPATH \[em] directories searched by cd +set -gx CDPATH . /home/youruser/projects /home/youruser + +# Path to your shared .gitignore boilerplate +set -gx GITIGNORE_BOILERPLATE \[ti]/.config/git/gitignore_boilerplate + +# SSH shortcuts +abbr -a sshr \[aq]ssh you\[at]your-server.local\[aq] +abbr -a sshw \[aq]ssh you\[at]work-server.example.com\[aq] + +# Docker context shortcuts +abbr -a dcr \[aq]docker context use my-remote-server\[aq] +abbr -a dcw \[aq]docker context use work-server\[aq] +\f[R] +.fi +.PP +Both files are sourced at the end of config.fish with an existence check +so the public config works cleanly on any machine without the private +repo. +.PP + * * * * * +.SH 11. VIEWING THIS MANUAL .SS With ov (recommended) .IP .nf diff --git a/docs/html/10-6-dependency-catalog.html b/docs/html/10-6-dependency-catalog.html index 21bcaa8..3180d7d 100644 --- a/docs/html/10-6-dependency-catalog.html +++ b/docs/html/10-6-dependency-catalog.html @@ -503,7 +503,7 @@ zoxide Smart cd with frecency direnv Per-directory environment loading paru AUR helper (Arch only; preferred) yay AUR helper (Arch only; fallback) -

Integrations

+

Integrations

wakatime   Developer time tracking
 tailscale  Mesh VPN client
diff --git a/docs/html/11-7-customization.html b/docs/html/11-7-customization.html index ca26cdc..96cbdc9 100644 --- a/docs/html/11-7-customization.html +++ b/docs/html/11-7-customization.html @@ -515,6 +515,31 @@ 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.

+

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.

+

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/fish plugin applies syntax highlight colors on first +run. Colors are stored in fish_variables (universal). To switch +variants, install a different theme from the themes/ directory:

+
fish_config theme save "Catppuccin Latte"
diff --git a/docs/html/12-8-fisher-plugins.html b/docs/html/12-8-fisher-plugins.html index a963126..2322d7f 100644 --- a/docs/html/12-8-fisher-plugins.html +++ b/docs/html/12-8-fisher-plugins.html @@ -481,7 +481,7 @@
-Next: +Next: Previous: 7. CUSTOMIZATION diff --git a/docs/html/13-9-installation.html b/docs/html/13-9-installation.html new file mode 100644 index 0000000..44e2a8a --- /dev/null +++ b/docs/html/13-9-installation.html @@ -0,0 +1,520 @@ + + + + + + + + 9. INSTALLATION + + + + + + +

9. INSTALLATION

+

This configuration is managed as a git repository. To deploy on a new +machine:

+
mv ~/.config/fish ~/.config/fish.bak   # back up any existing config
+git clone https://git.rootiest.dev/rootiest/fish-config.git ~/.config/fish
+

Then open a new Fish shell. Fisher and all plugins install +automatically on first launch and the Catppuccin Mocha theme is +applied.

+

Return Sentinel

+

config.fish ends with a return sentinel guard. Any lines appended +after it by a tool's setup command (starship init fish | source, zoxide +init fish | source, etc.) will have no effect. All integrations are +managed via conf.d/ files.

+

If a new tool's shell integration appears to do nothing, check +whether its setup command appended an init line below the sentinel and +create a dedicated conf.d/.fish instead.

+

Updating

+

Pull the latest changes from the upstream repository without needing +a configured git remote:

+
config-update              Fetch and apply the latest commits from upstream
+config-update --dry-run    Preview available changes without applying them
+config-update --force      Stash local changes, pull, then restore the stash
+

The remote URL (https://git.rootiest.dev/rootiest/fish-config.git) +is hard-coded, so this works on a fresh clone with no origin configured. +All git output is suppressed. Run exec fish after a successful update to +reload.

+
+ + diff --git a/docs/html/14-10-personalization.html b/docs/html/14-10-personalization.html new file mode 100644 index 0000000..54ed4eb --- /dev/null +++ b/docs/html/14-10-personalization.html @@ -0,0 +1,532 @@ + + + + + + + + 10. PERSONALIZATION + + + + + + +

10. PERSONALIZATION

+

Sensitive credentials and machine-specific settings are kept out of +version control in a private directory at ~/.config/.user-dots/fish/. +Two files are sourced automatically by config.fish if they exist:

+
~/.config/.user-dots/fish/
+├── secrets.fish   API keys, tokens, passwords, personal identifiers
+└── local.fish     Machine-specific paths and environment variables
+

fish_variables (auto-managed by fish) is excluded from this repo via +.gitignore. Do not commit it.

+

secrets.fish

+

Store anything you would not commit to a public repo: API keys, auth +tokens, passwords, and personal identifiers.

+
set -gx MY_NAME "Your Name"
+set -gx MY_EMAIL "you@example.com"
+set -gx GPG_RECIPIENT "you@example.com"
+set -gx GITHUB_TOKEN ghp_yourTokenHere
+set -gx OPENAI_API_KEY sk-proj-yourKeyHere
+set -gx GITEA_TOKEN yourGiteaTokenHere
+set -gx GITEA_CHOSEN_LOGIN your.gitea.instance
+set -gx KOPIA_PASSWORD yourKopiaPassword
+

local.fish

+

Store paths and variables specific to one machine — things that would +be wrong on any other system.

+
# CDPATH — directories searched by cd
+set -gx CDPATH . /home/youruser/projects /home/youruser
+
+# Path to your shared .gitignore boilerplate
+set -gx GITIGNORE_BOILERPLATE ~/.config/git/gitignore_boilerplate
+
+# SSH shortcuts
+abbr -a sshr 'ssh you@your-server.local'
+abbr -a sshw 'ssh you@work-server.example.com'
+
+# Docker context shortcuts
+abbr -a dcr 'docker context use my-remote-server'
+abbr -a dcw 'docker context use work-server'
+

Both files are sourced at the end of config.fish with an existence +check so the public config works cleanly on any machine without the +private repo.

+
+ + diff --git a/docs/html/13-9-viewing-this-manual.html b/docs/html/15-11-viewing-this-manual.html similarity index 96% rename from docs/html/13-9-viewing-this-manual.html rename to docs/html/15-11-viewing-this-manual.html index 33880e7..41b481d 100644 --- a/docs/html/13-9-viewing-this-manual.html +++ b/docs/html/15-11-viewing-this-manual.html @@ -5,7 +5,7 @@ - 9. VIEWING THIS MANUAL + 11. VIEWING THIS MANUAL