From 02c27c69076dc7740f63ed3c94b296979df25abe Mon Sep 17 00:00:00 2001 From: rootiest Date: Sat, 6 Jun 2026 03:14:36 -0400 Subject: [PATCH 1/4] feat(docs): add offline documentation, config_help viewer, and CI pipelines MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - docs/fish-config.md: curated terminal-optimized manual covering all public functions, keybindings, abbreviations, configuration variables, dependency catalog, and customization guide. Written for ov/bat/less readability rather than browser rendering — no callouts, no hyperlinks. Pandoc-compatible YAML front matter for man page compilation. - functions/config_help.fish: viewer function with fallback chain ov -> bat -> man -l -> less -> cat. Accepts an optional section keyword to jump directly to the first matching heading. - .gitea/workflows/man-page.yml: compiles docs/fish-config.md to docs/fish-config.1 via pandoc on every push to main that touches the source doc, then commits the result automatically. - .gitea/workflows/docs-drift.yml: opens a reminder issue whenever README.md changes without a corresponding docs/fish-config.md update in the same push. - README.md: documents config_help and the offline manual. - AGENTS.md: adds Convention 10 requiring offline doc to be updated alongside any function, keybinding, or config change. --- .gitea/workflows/docs-drift.yml | 45 ++ .gitea/workflows/man-page.yml | 37 + README.md | 13 + docs/fish-config.md | 1237 +++++++++++++++++++++++++++++++ functions/config_help.fish | 75 ++ 5 files changed, 1407 insertions(+) create mode 100644 .gitea/workflows/docs-drift.yml create mode 100644 .gitea/workflows/man-page.yml create mode 100644 docs/fish-config.md create mode 100644 functions/config_help.fish diff --git a/.gitea/workflows/docs-drift.yml b/.gitea/workflows/docs-drift.yml new file mode 100644 index 0000000..be5968f --- /dev/null +++ b/.gitea/workflows/docs-drift.yml @@ -0,0 +1,45 @@ +name: Offline docs drift reminder + +on: + push: + branches: + - main + paths: + - 'README.md' + +jobs: + remind: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + fetch-depth: 2 + + - name: Check whether offline doc changed in same push + id: drift + run: | + if git diff --name-only HEAD~1 HEAD | grep -q '^docs/fish-config\.md$'; then + echo "synced=true" >> "$GITHUB_OUTPUT" + else + echo "synced=false" >> "$GITHUB_OUTPUT" + fi + + - name: Open drift reminder issue + if: steps.drift.outputs.synced == 'false' + uses: actions/gitea-issue-create@v1 + with: + token: ${{ secrets.GITEA_TOKEN }} + title: "docs: README updated — review docs/fish-config.md for drift" + body: | + README.md was modified in commit ${{ github.sha }} but + `docs/fish-config.md` (the offline manual) was not updated in + the same push. + + Please review the README diff and update the offline documentation + if any functions, keybindings, abbreviations, or configuration + options were added, removed, or changed. + + Commit: ${{ github.sha }} + Branch: ${{ github.ref_name }} + labels: documentation diff --git a/.gitea/workflows/man-page.yml b/.gitea/workflows/man-page.yml new file mode 100644 index 0000000..aedb464 --- /dev/null +++ b/.gitea/workflows/man-page.yml @@ -0,0 +1,37 @@ +name: Generate man page + +on: + push: + branches: + - main + paths: + - 'docs/fish-config.md' + +jobs: + build-manpage: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + token: ${{ secrets.GITEA_TOKEN }} + + - name: Install pandoc + run: sudo apt-get update -qq && sudo apt-get install -y pandoc + + - name: Compile man page + run: | + pandoc --standalone \ + --from markdown \ + --to man \ + docs/fish-config.md \ + -o docs/fish-config.1 + + - name: Commit man page + run: | + git config user.name "Gitea Actions" + git config user.email "actions@gitea" + git add docs/fish-config.1 + git diff --cached --quiet && echo "No changes to commit" && exit 0 + git commit -m "chore(docs): regenerate fish-config.1 man page" + git push diff --git a/README.md b/README.md index 38f2c78..51f6b09 100644 --- a/README.md +++ b/README.md @@ -305,6 +305,19 @@ rm -f file.txt # Falls through to standard rm -f `conf.d/paru-wrapper.fish` and `conf.d/yay-wrapper.fish` auto-generate thin wrapper scripts at `~/.local/bin/paru` and `~/.local/bin/yay` on first shell start (when the respective AUR helper is installed). These wrappers tee all output to timestamped log files in `SCROLLBACK_HISTORY_DIR` and prune old logs to stay under `SCROLLBACK_HISTORY_MAX_FILES`. +### Offline Documentation + +A curated offline reference manual is available at `docs/fish-config.md`. It covers every function, keybinding, abbreviation, and configuration variable, written for terminal readability (no hyperlinks or GitHub-specific callouts). + +| Command | Description | +|---|---| +| `config_help` | Open the offline manual in the best available pager | +| `config_help ` | Jump directly to a section matching the keyword | + +The viewer falls back through: **ov** (syntax highlight + section navigation) → **bat** (syntax highlight) → **man -l** (pre-compiled man page) → **less** → **cat**. + +Examples: `config_help keybindings` · `config_help pkg` · `config_help fish-deps` · `config_help abbreviations` + ### Dependency Management `fish-deps` is a unified command for checking, installing, and updating all tools this config depends on. diff --git a/docs/fish-config.md b/docs/fish-config.md new file mode 100644 index 0000000..e736255 --- /dev/null +++ b/docs/fish-config.md @@ -0,0 +1,1237 @@ +--- +title: FISH-CONFIG +section: 7 +header: Fish Shell Configuration User Manual +date: June 2026 +author: Rootiest +--- + +# NAME + +fish-config - personal fish shell configuration for Fish 4.x with modern CLI tool integration + +# SYNOPSIS + + config_help [SECTION] + +Open this manual in the best available pager. Optionally jump to a section +by keyword: + + config_help keybindings + config_help pkg + config_help abbreviations + config_help logs + +# DESCRIPTION + +A production-grade Fish shell configuration targeting Fish 4.x. It provides: + +- Drop-in replacements for common Unix tools (ls, cat, rm, du, ping, less) +- Deep Kitty and WezTerm terminal integration: tab/window/pane management from + the command line +- Scrollback history snapshots saved to ~/.terminal_history on session exit +- Automatic Python virtualenv activation on directory change +- Cross-platform package management via pkg and fish-deps +- AI session helpers for Claude Code and Antigravity +- Catppuccin Mocha color theme throughout + +The configuration is split across: + + 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 + +--- + +# TABLE OF CONTENTS + + 1. Configuration Variables + 2. PATH Setup + 3. Key Bindings + 4. Abbreviations + 4.1 Editors + 4.2 Navigation and Listing + 4.3 Git + 4.4 Terminal Windows, Tabs, and Panes + 4.5 Chezmoi + 4.6 Docker + 4.7 Systemctl + 4.8 AI Assistants + 4.9 History Expansion + 4.10 Miscellaneous + 5. Functions Reference + 5.1 File and Directory + 5.2 Navigation + 5.3 Editors and Viewers + 5.4 Git and Version Control + 5.5 Package Management + 5.6 Dependency Management + 5.7 System and Monitoring + 5.8 Terminal Management + 5.9 Clipboard + 5.10 Network + 5.11 Pager and Logging + 5.12 AI and Developer Tools + 5.13 Media and Utilities + 5.14 Miscellaneous + 6. Dependency Catalog + 7. Customization + 8. Fisher Plugins + 9. Viewing This Manual + +--- + +# 1. CONFIGURATION VARIABLES + +These variables are exported from config.fish on every interactive session. +Override them in ~/.config/.user-dots/fish/local.fish. + +## Environment Directories (XDG) + + XDG_CONFIG_HOME ~/.config + XDG_CACHE_HOME ~/.cache + XDG_DATA_HOME ~/.local/share + XDG_STATE_HOME ~/.local/state + +Tools that respect XDG are directed to these paths rather than polluting $HOME. + +## Tool Homes (XDG-compliant) + + CARGO_HOME $XDG_DATA_HOME/cargo + RUSTUP_HOME $XDG_DATA_HOME/rustup + GOPATH $XDG_DATA_HOME/go + BUN_INSTALL $XDG_DATA_HOME/bun + NPM_CONFIG_PREFIX $XDG_DATA_HOME/npm-global + GNUPGHOME $XDG_CONFIG_HOME/gnupg + WAKATIME_HOME $XDG_CONFIG_HOME/wakatime + +## Editor and Pager + + EDITOR nvim (falls back to vi if nvim is absent) + VISUAL same as EDITOR + SUDO_EDITOR same as EDITOR + PAGER ov (falls back to less) + +## Scrollback History + + SCROLLBACK_HISTORY_DIR ~/.terminal_history + SCROLLBACK_HISTORY_MAX_FILES 100 + +Scrollback logs accumulate in SCROLLBACK_HISTORY_DIR as timestamped files. +When the count exceeds SCROLLBACK_HISTORY_MAX_FILES the oldest are pruned +automatically on exit. Use `logs` to browse them interactively. + +## Other + + GPG_TTY $(tty) — ensures GPG passphrase prompts work + CLAUDE_CODE_NO_FLICKER 1 — suppress terminal flicker in Claude Code + CDPATH . ~/projects ~ + +--- + +# 2. PATH SETUP + +Directories prepended to PATH in this order (first wins): + + ~/.local/bin Standard user-local executables + ~/Applications User-installed standalone apps + ~/scripts Personal shell scripts + ~/bin Cargo binaries (appended — lowest priority) + $BUN_INSTALL/bin Bun runtime and global packages + $NPM_CONFIG_PREFIX/bin Global npm packages + ~/.lmstudio/bin LM Studio CLI + ~/.resend/bin Resend CLI + ~/.fzf/bin fzf binary (git-installed) + +Cargo binaries are intentionally appended (lowest priority) to avoid +shadowing system-installed Rust tools. + +--- + +# 3. KEY BINDINGS + +The shell uses Vi key bindings (fish_vi_key_bindings). All custom bindings +are active in Insert, Normal, and Visual modes unless noted. + + Binding Action + ───────────────────────────────────────────────────────────────────── + Ctrl+G Insert the head of the previous command's last path + argument. Equivalent to !$:h in Bash. + Example: previous = "cd /usr/local/bin" + Ctrl+G inserts "/usr/local" + + Ctrl+F Interactive history substitution. Type old/new then + press Ctrl+F to apply s/old/new/ to the previous + command. Equivalent to !!:s/old/new/ in Bash. + Example: previous = "echo this is a test" + type "this is/that was", press Ctrl+F + result = "echo that was a test" + + Ctrl+Alt+U Strip the first token of the current command line, + leaving arguments in place with the cursor at the + start. Useful for quickly retyping the command. + Example: "mkdir new_folder" -> " new_folder" + + Ctrl+Alt+= Evaluate the current command line buffer with + Qalculate! (qalc) and print the result inline. + Requires qalc to be installed. + Example: type "150 * 1.08", press Ctrl+Alt+= + prints 162 + + Ctrl+Enter Smart execute: runs commands instantly without + pressing Enter a second time for certain fast-path + commands (speedtest-fast, etc.). + + @@ FZF inline picker. Type @@ anywhere on the command + line to open an fzf picker and insert a selection + at the cursor position. + +## FZF Bindings (from fzf --fish integration) + + Ctrl+R Search shell history with fzf + Ctrl+T Insert a file path from fzf + Alt+C cd into a directory chosen with fzf + +--- + +# 4. ABBREVIATIONS + +Abbreviations expand when you press Space or Enter. They are terminal-aware: +some expand differently in Kitty vs WezTerm vs other terminals. + +## 4.1 Editors + + n / nv / neovim nvim + e edit + se sudoedit + k kate + editt Open new tab with nvim (terminal-aware) + cdnv cd ~/.config/nvim + cdnvn cd ~/.config/nvim; nvim + +## 4.2 Navigation and Listing + + l ls + lS lss (sort by size) + lsR lsr (sort by time, oldest first) + lX lx (sort by extension) + lT lt (tree, depth 2) + lsT lstree (full recursive tree) + lzd ld (lazydocker) + cdi zi (interactive zoxide picker) + +## 4.3 Git + + g git + lg lazygit + gitig / git-ignore gi (generate .gitignore) + +## 4.4 Terminal Windows, Tabs, and Panes + +These abbreviations control the terminal emulator. Each has a Kitty +variant and a WezTerm variant; the correct one is inserted based on +$TERM or $TERM_PROGRAM. + + :w New OS window + :wv Split pane horizontally (new pane below) + :wh Split pane vertically (new pane to the right) + :wo Detach current window to its own OS window + :wot Move current pane to a new tab + :t New tab + :tl Set tab title + :tw Set window title + :twk Rename workspace (WezTerm only) + :tp Focus previous tab + :tn Focus next tab + :q Close current pane/window + :Q Close current tab + :sw spwin (spawn new OS window) + +Quick-navigate shortcuts open windows/tabs/panes with preset working dirs: + + :tgk New tab at ~/.config/kitty + :tgn New tab at ~/.config/nvim + :tgf New tab at ~/.config/fish + :tgh New tab at ~ + :tgcz New tab at chezmoi source dir + :tgcm New tab at chezmoi source dir + :tgp New tab at ~/projects + :tgr New tab at / (root) + +Prefixes :wg* and :wvg* / :whg* open OS windows or splits to the same +set of dirs, respectively. + +Prefixes :cd* open tabs with a quick cd shortcut: + + :cdn cd ~/.config/nvim + :cdf cd ~/.config/fish + :cdh cd ~ + :cdcz cd to chezmoi source + :cdp cd ~/projects + +Appending n to any :cd* abbreviation also runs nvim after changing dir. + +## 4.5 Chezmoi + + cm / cme / cmi / cmap / cmad / cmrm / cmcd / + cz / cze / czi / czap / czad / czrm / czcd + + cm / cz chezmoi + cmcd / czcd chezmoi cd + cme / cze chezmoi edit + cmad / czad chezmoi add + cmap / czap chezmoi apply + cmrm / cmf / czrm / czf chezmoi forget + cmi / czi chezmoi init + +## 4.6 Docker + + dcl docker context use default + dcls docker context ls + lzd ld (lazydocker) + +## 4.7 Systemctl + + sc systemctl + ssc sudo systemctl + scu systemctl --user + st systemctl status + scs sudo systemctl start + scr sudo systemctl restart + ssct sudo systemctl start + sscs sudo systemctl stop + sscr sudo systemctl restart + +## 4.8 AI Assistants + + ag antigravity + ag. antigravity . + v antigravity-ide + s wezterm ssh (WezTerm only) + +## 4.9 History Expansion + +These are implemented as keybinding helpers, but can also be typed: + + !^ Expand to first argument of previous command + !* Expand to all arguments of previous command + typo_sub Interactive typo substitution (Ctrl+F) + bang_string !string expansion + bang_search !?string search + bang_minus_n !-n (nth-previous command) + +## 4.10 Miscellaneous + + /exit exit + :q Close pane (alias for terminal close) + :Q Close tab + sudu sudo -s + kt kitty (Kitty only) + c cat + speedtest-fast fast-cli + bl bd list + bs bd sync + bC bd create --title + bsh bd show + lb lazybeads + +--- + +# 5. FUNCTIONS REFERENCE + +## 5.1 File and Directory + +### cat + + Synopsis: cat [args...] + Wraps bat for files with syntax highlighting and line numbers. + Passes directories to ls. Falls back to /usr/bin/cat. + + cat README.md + cat ~/projects/myapp + +### copy + + Synopsis: copy + Wraps cp, stripping trailing slashes from source directories to + prevent unintended nesting inside the destination. + + copy ./mydir/ ~/backup # copies mydir INTO backup, not backup/mydir/ + +### du + + Synopsis: du [--disk|--dir|--dua] [args...] + Smart disk-usage dispatcher: + --disk force duf (disk-level free/used overview) + --dir force dust (per-directory tree breakdown) + --dua force dua (fast space analyzer) + Without flags, routes to the most appropriate tool by context. + + du ~/Downloads + du --disk + +### dusize + + Synopsis: dusize [dir] + Human-readable disk usage for a directory via du -sh. Defaults to cwd. + + dusize ~/Videos + +### lD + + Synopsis: lD [args...] + Lists directories only in long format with icons. Uses eza, falls back + to lsd, then system ls. + + lD ~/projects + +### ls + + Synopsis: ls [args...] + Lists files in long format with icons and hyperlinks. Uses eza, falls + back to lsd, then system ls. + + ls + ls -a ~/projects + +### lsr + + Synopsis: lsr [args...] + Lists files sorted by modification time, oldest first. Uses eza. + +### lss + + Synopsis: lss [args...] + Lists files sorted by size with gradient color scaling. Uses eza. + +### lstree + + Synopsis: lstree [args...] + Full recursive tree view with icons. Uses eza. + + lstree ~/projects/myapp + +### lt + + Synopsis: lt [args...] + Tree view limited to depth 2 with icons. Uses eza. + + lt ~/projects + +### ltr + + Synopsis: ltr [args...] + Lists files sorted by modification time, oldest first, long format with + age-based gradient scaling. Uses eza. + +### lx + + Synopsis: lx [args...] + Lists files sorted by extension, long format. Uses eza. + +### mkdir + + Synopsis: mkdir [args...] + Interactive mkdir that prints a tree of created directories. + Falls back to mkdir -p silently. + + mkdir ~/projects/myapp/src + +### mkcd + + Synopsis: mkcd [-s] + Creates a directory (including parents) and cd into it. Prints a tree + of created dirs by default; -s/--silent suppresses output. + + mkcd ~/projects/newapp/src + +### poke + + Synopsis: poke [file...] + Creates files via touch, automatically creating any missing parent + directories first. + + poke ~/projects/new/src/main.fish + +### rm + + Synopsis: rm [-e [opts] | -S | args...] + Safe rm wrapper routing to trash: + + (no args) List current trash contents + -e/--empty Empty the trash (pass options to trash-empty) + -S/--secure Permanently delete via rm -rf + fstrim (irreversible) + -r/-R/--recursive Move to trash + Move to trash (safe delete) + + Falls back to /usr/bin/rm when trash is unavailable. + + rm file.txt # moves to trash + rm -e # empty trash + rm -S sensitive.pem # permanent delete + +### scrub + + Synopsis: scrub [-a] [-d] [-h] + Recursively removes OS metadata, editor artifacts, compiler output, + and dev caches using fd. + + -a/--aggressive Also removes node_modules, logs, .cache, IDE dirs, + AI session artifacts + -d/--dry-run Print what would be removed without deleting + + scrub + scrub -a + scrub -d + +--- + +## 5.2 Navigation + +### cdi + + Synopsis: cdi [query] + Interactive directory picker combining zoxide frecency with fzf. + Equivalent to zi. + + cdi myproject + +### clone + + Synopsis: clone [args...] + Clone a git repository into a new Kitty window. Kitty-only. + + clone https://github.com/user/repo.git + +### clonet + + Synopsis: clonet [args...] + Clone a git repository into a new Kitty tab. Kitty-only. + + clonet https://github.com/user/repo.git + +--- + +## 5.3 Editors and Viewers + +### edit + + Synopsis: edit [args...] + Opens files in nvim. Falls back to $EDITOR, nano, vi. + + edit ~/.config/fish/config.fish + +### fc + + Synopsis: fc [command_prefix] + Edit the last shell command (or one matching a prefix) in $EDITOR, + then execute the result. Bash-style fc behaviour. + + fc + fc git + +### less + + Synopsis: less [args...] + Pager wrapper with fallback chain: $PAGER -> ov -> less -> more -> cat. + + less /var/log/syslog + +### rawfish + + Synopsis: rawfish [args...] + Launches Fish with NO_TMUX=1, bypassing any tmux auto-attach logic. + Useful when you need a clean shell without session management. + +### view + + Synopsis: view [args...] + Opens files in nvim read-only mode (-R). Falls back to less. + + view /etc/fstab + +--- + +## 5.4 Git and Version Control + +### branch + + Synopsis: branch + Switches to a local branch, or creates it if it does not exist. + + branch feature/new-ui + +### gi + + Synopsis: gi [-h] [-b] [-p] [-s] [-l] [targets...] + Generates .gitignore content from the gitignore.io API with MD5-based + deduplication (patterns already present are not re-appended). + + -b/--boilerplate Append generic boilerplate first + -p/--prompt Prompt interactively for targets + -s/--stdout Print to stdout instead of appending to .gitignore + -l/--list List all available targets + targets Comma-separated or space-separated target names + + gi python,venv + gi -b -p + gi -s node > .gitignore + +### git-clean + + Synopsis: git-clean [-f] + Fetches and prunes the remote, fast-forwards the current branch, then + deletes local branches whose remote tracking branch has been deleted. + Switches to main/master automatically if the current branch is orphaned. + + -f/--force Force-delete unmerged branches too + + git-clean + git-clean --force + +### gitup + + Synopsis: gitup [args...] + Fetches updates from the remote and shows git status. Extra args are + forwarded to git fetch. + + gitup + gitup --all + +### gitui + + Synopsis: gitui [args...] + Launches gitui with the Catppuccin Frappe theme pre-applied. + +### hist + + Synopsis: hist + Searches shell history with fzf, inserts the selection into the command + line, and copies it to the clipboard via wl-copy. + +--- + +## 5.5 Package Management + +### pkg + + Synopsis: pkg [-h] [-i|-u] [package...] + Installs or removes packages using the detected system package manager. + Supports: paru, yay, pacman, apt, dnf, zypper, yum, brew, pkg. + + (no flag) Auto mode: installs missing packages, removes installed ones + -i/--install Force install + -u/--uninstall Force uninstall + + pkg firefox # auto: install if missing, remove if present + pkg -i ripgrep fd # force install + pkg -u cowsay # force uninstall + + The package-installed check uses the correct query for each PM: + pacman/paru/yay pacman -Qi + apt dpkg -s + dnf/zypper/yum rpm -q + brew brew list + pkg pkg info + +### search + + Synopsis: search [args...] + Interactive AUR package search and install via paru or yay. + Arch Linux only. + + search neovim + +### upgrade + + Synopsis: upgrade + Full system upgrade via paru -Syu --noconfirm or yay -Syu --noconfirm. + Arch Linux only. + +### cleanup + + Synopsis: cleanup + Lists and removes orphan packages via pacman, logging their names to + ~/.removed_orphans. Arch Linux only. + +### parur + + Synopsis: parur + Opens an fzf picker of all installed packages (with pacman -Qi previews), + then removes the selected packages via paru or yay. Arch Linux only. + + parur + +--- + +## 5.6 Dependency Management + +### fish-deps + + Synopsis: fish-deps [status|install|update|sync] + Unified command for managing all tools this configuration depends on. + + status (default) Show installed/missing status grouped by tier + install Interactively install each missing dependency + update Update all installed dependencies + sync Install missing deps, then update all + + Install method priority (highest to lowest): + 1. git+cargo source build (fish shell itself) + 2. cargo (Rust tools — gets latest crate version) + 3. system PM (paru/apt/brew/etc.) + 4. git clone (fzf) + 5. curl installer (starship, fisher, uv) + 6. pipx (Python tools) + + When multiple methods are available you are prompted to choose. + + Dependencies are grouped into three tiers: + + Required uv, cargo, fish, fisher, starship, fzf, zoxide, + direnv, paru/yay + Integrations wakatime, tailscale + Recommended eza, lsd, bat, btop, dust, duf, prettyping, ov, + ripgrep, lazygit, lazydocker, trash, kitty, wezterm + + fish-deps + fish-deps install + fish-deps update + fish-deps sync + +### check_fish_deps + + Synopsis: check_fish_deps + Backwards-compatibility alias for `fish-deps status`. + +--- + +## 5.7 System and Monitoring + +### top + + Synopsis: top [args...] + Launches btop as a modern resource monitor. Falls back to system top. + +### swapstat + + Synopsis: swapstat + Displays a colorized memory report: kernel swappiness, zRAM compression + ratio, zRAM device details, and active swap priorities. + +### sbver + + Synopsis: sbver [--brief] + Verifies Secure Boot signatures on all EFI binaries tracked by sbctl. + Color-codes results: green checkmark (verified), red X (unsigned). + Prints a pass/fail summary. + + --brief Suppress per-file output, show only the summary + + sbver + sbver --brief + +### ports + + Synopsis: ports + Lists active TCP listeners with lsof, showing port/address without + hostname resolution. + +### screensleep + + Synopsis: screensleep + Turns off the display via KDE PowerDevil's "Turn Off Screen" action, + invoked through busctl. + +### lock + + Synopsis: lock + Locks the current desktop session using loginctl lock-session. + +### sudo-toggle + + Synopsis: sudo-toggle + Toggles the sudo NOPASSWD rule on/off via /etc/sudoers.d/nofail-toggle. + Useful for automated tasks that would otherwise require password entry. + +### limine-edit + + Synopsis: limine-edit + Opens /boot/limine.conf in sudoedit, then automatically re-enrolls the + config hash, runs CachyOS boot hooks, and re-signs Secure Boot files. + Combines the edit and sign steps into a single command. + +--- + +## 5.8 Terminal Management + +### tab + + Synopsis: tab [args...] + Opens a new tab in Kitty (kitty @ launch --type=tab), WezTerm + (wezterm cli spawn), or Konsole. Uses current working directory, + or $cdto if set. + + tab + +### split + + Synopsis: split [-h|-v] [command...] + Opens a new pane in Kitty or WezTerm, optionally running a command. + + -h/--horizontal (default) Split below + -v/--vertical Split to the right + + split + split -v nvim README.md + +### spwin + + Synopsis: spwin [args...] + Spawns a new terminal OS window in Kitty (via spawn-window.sh or + kitty @ launch --type=os-window) or WezTerm (wezterm cli spawn --new-window). + +### detach + + Synopsis: detach [-h] [--version] [args...] + Runs a command fully detached via nohup with stdout/stderr discarded. + The command survives the current session. + + detach rsync -a ./data remote:/backup/ + +### bkg + + Synopsis: bkg [args...] + Launches a command in the background via nohup with output discarded. + Simpler than detach; no version flag. + + bkg firefox + +### ssh + + Synopsis: ssh [args...] + In Kitty, wraps ssh with kitten ssh for better terminal integration + (multiplexing, copy/paste support). Falls back to system ssh elsewhere. + + ssh user@host + +--- + +## 5.9 Clipboard + +### y + + Synopsis: y [text...] + Copies text to the clipboard via wl-copy (Wayland) or xclip (X11). + Reads from stdin if no arguments given. + + y "hello world" + ls | y + cat file.txt | y + +### p + + Synopsis: p [args...] + Outputs clipboard contents to stdout. + + p | grep foo + p > file.txt + +### paste + + Alias for p. Identical behaviour. + +--- + +## 5.10 Network + +### gip + + Synopsis: gip + Fetches and prints both the public IPv4 and IPv6 address via + icanhazip.com. + +### gip4 + + Synopsis: gip4 + Fetches and prints the public IPv4 address. + +### gip6 + + Synopsis: gip6 + Fetches and prints the public IPv6 address. Returns 1 if IPv6 is + unavailable. + +### ping + + Synopsis: ping [args...] + Wraps prettyping with --nolegend. Pass --legend to show the legend. + Falls back to system ping. + + ping google.com + +### qr + + Synopsis: qr [text...] + Generates a UTF-8 QR code from text or stdin. Uses qrencode locally; + falls back to the qrenco.de API. + + qr "https://example.com" + echo "https://example.com" | qr + +--- + +## 5.11 Pager and Logging + +### logs + + Synopsis: logs [-c ] + Interactively browses terminal log files sorted newest-first using fzf. + + -c/--category Filter to: scrollback, paru, or yay + + Keybindings inside the fzf browser: + Enter Open in $PAGER + Ctrl+E Open in $EDITOR + Ctrl+D Delete (with confirmation) + ? Toggle keybind help overlay + + Paru and yay logs open in ov with syntax highlighting and sticky section + headers. Scrollback logs open in ov with per-command sticky prompt headers + based on OSC 133 markers. + + logs + logs -c paru + logs -c scrollback + +### smart_exit + + Synopsis: smart_exit [-n] + Closes the shell session. In Kitty, captures the terminal scrollback to + a timestamped log file in $SCROLLBACK_HISTORY_DIR before exiting. + Automatically prunes the oldest logs when the count exceeds + $SCROLLBACK_HISTORY_MAX_FILES. + + -n/--no-log Exit without saving a scrollback log + + The exit builtin is wired to smart_exit for interactive sessions. + Typing exit or Ctrl+D behaves identically to smart_exit. + + smart_exit + smart_exit --no-log + +--- + +## 5.12 AI and Developer Tools + +### antigravity + + Synopsis: antigravity [args...] + Runs the agy CLI (Antigravity AI assistant) with noisy deprecation + warnings filtered from stderr. + + antigravity chat + +### antigravity-ide + + Synopsis: antigravity-ide [args...] + Runs the antigravity-ide editor with warnings filtered. + +### antigravity-resume + + Synopsis: antigravity-resume + Resumes the most recent Antigravity session from the .antigravity_session + file in the current directory, or opens an interactive fzf picker if no + session file is found. + +### claude-resume + + Synopsis: claude-resume + Resumes the most recent Claude Code session from the .claude_session + file in the current directory, or opens an interactive fzf picker. + +### claude-docs + + Synopsis: claude-docs + Invokes Claude Code to analyze recent repository changes and update + README.md, ensuring all documented features and examples are accurate. + +### claude-pr + + Synopsis: claude-pr + Invokes Claude Code to run the full PR workflow: create branch, + conventional commit, verification, push, and open a PR with a manual + verification checklist. + +### code-resume + + Synopsis: code-resume + Resumes the most recent AI session (Claude or Antigravity), preferring + the newest session file found in the current directory. + +### superpowers + + Synopsis: superpowers [on|off] [-g] + Enables or disables the Superpowers plugin for Antigravity and Claude + Code at workspace/project scope (default) or user scope (-g/--global). + + superpowers on + superpowers off -g + +--- + +## 5.13 Media and Utilities + +### dng2avif + + Synopsis: dng2avif [-i ] [-o ] [-q ] [-s ] [input.dng] + Converts a DNG raw image to a 10-bit HDR AVIF using an ImageMagick, + ffmpeg, avifenc pipeline with metadata sync via exiftool. + + -i/--input Input file (or positional arg) + -o/--output Output file (default: same name, .avif extension) + -q/--quality Quality 0-100 (default 92) + -s/--speed Encoding speed 0-10 (default 3) + + dng2avif photo.dng + dng2avif -q 85 -s 5 -i shot.dng -o out.avif + +### steam-dl + + Synopsis: steam-dl + Launches Steam under systemd-inhibit, preventing the system from going + idle or sleeping while a download is in progress. + +### spark + + Synopsis: spark [--min=] [--max=] [numbers...] + Renders a Unicode sparkline bar chart for a sequence of numbers. + Reads from stdin if no numbers are given. + + spark 1 1 2 5 14 42 + echo "3 7 2 9 1" | spark + +--- + +## 5.14 Miscellaneous + +### bash + + Synopsis: bash [args...] + Switches to bash, with XDG config applied. On exit, $SHELL is reset + back to fish. + +### bd-pull + + Synopsis: bd-pull + Fetches unlinked Gitea issues and creates local Beads entries, updating + issue titles with the assigned Beads IDs. + Requires $GITEA_TOKEN and $GITEA_URL to be set. + + bd-pull rootiest/fish-config + +### cheat + + Synopsis: cheat [args...] + Displays a colorized cheatsheet using cheat -c, falls back to tldr, + then man. + + cheat tar + cheat git + +### cffetch / ffetch + + Synopsis: cffetch [args...] / ffetch [args...] + Clears the screen and displays system information via fastfetch with + the custom config at ~/.fastfetch.jsonc. Falls back to neofetch. + +### dockup + + Synopsis: dockup [-h] [directory] + Pulls latest Docker images, restarts services in the given Docker + Compose project, and prunes dangling images. + + dockup ~/myapp + +### joplin + + Synopsis: joplin [args...] + Runs the Joplin CLI with Node.js deprecation warnings suppressed. + + joplin ls + +### ld + + Synopsis: ld + Launches lazydocker targeting the currently active Docker context, + detected via docker context inspect. + +### replay + + Synopsis: replay + Runs Bash commands and replays any resulting changes to environment + variables, aliases, and the working directory back into the current + Fish session. Useful for sourcing Bash scripts. + + replay "source ~/.bashrc" + replay "export FOO=bar" + +### tmux-clean + + Synopsis: tmux-clean + Kills all detached (unattached) tmux sessions, leaving attached ones + running. + +### wake-lock + + Synopsis: wake-lock [args...] + Runs a command under systemd-inhibit, preventing the system from going + idle or sleeping until the command completes. + + wake-lock rsync -avz src/ dest/ + +### zellij + + Synopsis: zellij [args...] + Launches zellij with the Catppuccin Mocha theme applied. + +--- + +# 6. DEPENDENCY CATALOG + +fish-deps manages these tools. Run `fish-deps` to check status, or +`fish-deps install` to install missing ones. + +## Required + + uv Python package manager (Astral) + cargo Rust toolchain (via rustup) + fish Fish shell >= 4.0 + fisher Fish plugin manager + starship Cross-shell prompt + fzf Fuzzy finder + zoxide Smart cd with frecency + direnv Per-directory environment loading + paru AUR helper (Arch only; preferred) + yay AUR helper (Arch only; fallback) + +## Integrations + + wakatime Developer time tracking + tailscale Mesh VPN client + +## Recommended + + eza Modern ls replacement + lsd ls replacement (fallback to eza) + bat Syntax-highlighted cat + btop Modern resource monitor + dust Disk usage tree (Rust) + duf Disk usage/free overview + prettyping Colorized ping wrapper + ov Modern pager (replaces less) + ripgrep Fast line search + lazygit Terminal git UI + lazydocker Terminal docker UI + trash Safe delete (trash-cli) + kitty GPU-accelerated terminal (primary) + wezterm GPU-accelerated terminal (alternative) + +## Install Methods + +The install priority for each tool: + + cargo Rust tools (eza, lsd, bat, dust, ov, ripgrep, trashy, zoxide, + starship) — always gets the latest crate version + system PM paru / apt / brew / dnf / etc. — for tools without a crate + git clone fzf — installed from GitHub to ~/.fzf/ + curl starship installer, fisher bootstrap, uv installer + pipx Python-based tools + +--- + +# 7. CUSTOMIZATION + +## Machine-local Configuration + +Place machine-specific settings that should not be committed to git in: + + ~/.config/.user-dots/fish/local.fish + +Typical uses: additional PATH entries, local aliases, hostname-specific env +vars, work-specific tool configs. + +## Secrets and API Keys + + ~/.config/.user-dots/fish/secrets.fish + +Store API tokens, GPG keys, private credentials here. This file is never +committed. + +Both files are sourced at the end of config.fish on every interactive +session, so they can override anything set earlier. + +## 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. + +--- + +# 8. FISHER PLUGINS + +Fisher is bootstrapped automatically on first shell start if not present. +The plugin list is maintained in fish_plugins at the config root. + + jorgebucaran/fisher Plugin manager itself + catppuccin/fish Catppuccin Mocha color theme + PatrickF1/fzf.fish fzf integration for Fish + franciscolourenco/done Desktop notification when long commands finish + jorgebucaran/autopair.fish Auto-pair brackets and quotes + meaningful-ooo/sponge Remove failed commands from history + nickeb96/puffer-fish !! / !$ / ./ expansion + +Run `fisher update` to update all plugins, or `fish-deps update` which +calls fisher update as its first step. + +--- + +# 9. VIEWING THIS MANUAL + +## With ov (recommended) + + config_help + +ov renders the Markdown with syntax highlighting and section-based +navigation. Use , and . to jump between sections. Press / to search. + +## With bat + + bat --language=markdown --paging=always ~/.config/fish/docs/fish-config.md + +## As a man page (if compiled) + + man -l ~/.config/fish/docs/fish-config.1 + +## Jumping to a section + + config_help keybindings + config_help abbreviations + config_help pkg + config_help logs + config_help fish-deps + +The keyword is matched case-insensitively against section headings. diff --git a/functions/config_help.fish b/functions/config_help.fish new file mode 100644 index 0000000..5901028 --- /dev/null +++ b/functions/config_help.fish @@ -0,0 +1,75 @@ +# Copyright (C) 2026 Rootiest +# SPDX-License-Identifier: AGPL-3.0-or-later + +# SYNOPSIS +# config_help [section] +# +# DESCRIPTION +# Opens the offline fish shell configuration manual in the best available +# pager. Falls back through ov -> bat -> man -> less -> cat. +# If a section keyword is provided, the pager opens at the first heading +# that matches the keyword (case-insensitive). +# +# ARGUMENTS +# section Optional keyword to jump to a matching section heading +# +# RETURNS +# 0 Manual displayed +# 1 Documentation file not found +# +# EXAMPLE +# config_help +# config_help keybindings +# config_help pkg +# config_help fish-deps +function config_help --description 'Open the offline fish shell configuration manual' + set -l doc_file "$__fish_config_dir/docs/fish-config.md" + set -l man_file "$__fish_config_dir/docs/fish-config.1" + + if not test -f "$doc_file" + set_color red + echo "error: documentation not found at $doc_file" >&2 + set_color normal + return 1 + end + + # ── Resolve section start line ─────────────────────────────── + set -l start_line 1 + if test -n "$argv[1]" + set -l found (grep -n -im 1 "^#\+.*$argv[1]" "$doc_file" | cut -d: -f1) + if test -n "$found" + set start_line $found + else + set_color yellow + echo "note: no section matching '$argv[1]' — opening at top" >&2 + set_color normal + end + end + + # ── Viewer fallback chain ──────────────────────────────────── + if type -q ov + ov --syntax --syntax-name markdown \ + --section-delimiter "^#" \ + --section-header \ + +"$start_line" "$doc_file" + + else if type -q bat + if test $start_line -gt 1 + # bat can't jump to a line in paging mode; show a hint instead + set_color brblack + echo "note: bat pager active — use / to search for your section" >&2 + set_color normal + end + bat --language=markdown --paging=always "$doc_file" + + else if test -f "$man_file" + # Pre-compiled man page as a pager-independent fallback + man -l "$man_file" + + else if type -q less + less +"$start_line" "$doc_file" + + else + cat "$doc_file" + end +end From 368b714a98619e21e672e2ba22d55b28bfd114fc Mon Sep 17 00:00:00 2001 From: rootiest Date: Sat, 6 Jun 2026 04:09:12 -0400 Subject: [PATCH 2/4] fix(config_help): reliable section lookup and jump via index + tail-slice MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add docs/fish-config.index mapping 100+ keyword aliases to exact heading text; config_help looks up here first, falls back to normalized heading scan (strips non-alphanumeric, lowercases both sides) for unknown terms. - Resolve line numbers at runtime with grep -F so the index never goes stale from doc edits — only heading renames require an update. - Fix section jump: --section-header pins delimiter lines as sticky headers removing them from ov pattern-search scope. Replace --pattern with tail -n +$start_line piped before ov; the target section is the first line so no search is needed and forward section nav still works. - Fix empty sections sidebar: ov matches --section-delimiter against logical (ANSI-stripped) text, so "^#" is correct for bat-colored output; the previous ANSI escape-sequence regex never matched anything. --- docs/fish-config.index | 176 +++++++++++++++++++++++++++++++++++++ docs/fish-config.md | 11 ++- functions/config_help.fish | 88 ++++++++++++++++--- 3 files changed, 262 insertions(+), 13 deletions(-) create mode 100644 docs/fish-config.index diff --git a/docs/fish-config.index b/docs/fish-config.index new file mode 100644 index 0000000..b26b879 --- /dev/null +++ b/docs/fish-config.index @@ -0,0 +1,176 @@ +# Fish Config Help Index +# Format: keyword=exact heading text as it appears in fish-config.md +# Multiple keywords may map to the same heading. +# Update this file whenever headings are added, removed, or renamed. +# config_help uses this for fast exact lookups; unknown keywords fall back +# to a normalized heading scan automatically. + +# ── Top-level ───────────────────────────────────────────────── +name=# NAME +synopsis=# SYNOPSIS +description=# DESCRIPTION +toc=# TABLE OF CONTENTS +contents=# TABLE OF CONTENTS + +# ── Section 1: Configuration Variables ─────────────────────── +variables=# 1. CONFIGURATION VARIABLES +config=# 1. CONFIGURATION VARIABLES +xdg=## Environment Directories (XDG) +toolhomes=## Tool Homes (XDG-compliant) +editor=## Editor and Pager +pager=## Editor and Pager +scrollback=## Scrollback History + +# ── Section 2: PATH ─────────────────────────────────────────── +path=# 2. PATH SETUP + +# ── Section 3: Key Bindings ─────────────────────────────────── +keybindings=# 3. KEY BINDINGS +bindings=# 3. KEY BINDINGS +key-bindings=# 3. KEY BINDINGS +keys=# 3. KEY BINDINGS +fzf-bindings=## FZF Bindings (from fzf --fish integration) +fzf=## FZF Bindings (from fzf --fish integration) + +# ── Section 4: Abbreviations ────────────────────────────────── +abbreviations=# 4. ABBREVIATIONS +abbr=# 4. ABBREVIATIONS +abbrs=# 4. ABBREVIATIONS +editors-abbr=## 4.1 Editors +nav=## 4.2 Navigation and Listing +navigation=## 4.2 Navigation and Listing +listing=## 4.2 Navigation and Listing +git-abbr=## 4.3 Git +terminal=## 4.4 Terminal Windows, Tabs, and Panes +panes=## 4.4 Terminal Windows, Tabs, and Panes +windows=## 4.4 Terminal Windows, Tabs, and Panes +tabs=## 4.4 Terminal Windows, Tabs, and Panes +chezmoi=## 4.5 Chezmoi +docker=## 4.6 Docker +systemctl=## 4.7 Systemctl +systemd=## 4.7 Systemctl +ai-abbr=## 4.8 AI Assistants +history=## 4.9 History Expansion +misc-abbr=## 4.10 Miscellaneous + +# ── Section 5: Functions ────────────────────────────────────── +functions=# 5. FUNCTIONS REFERENCE +files=## 5.1 File and Directory +cat=### cat +copy=### copy +du=### du +dusize=### dusize +ls=### ls +lsr=### lsr +lss=### lss +lstree=### lstree +lt=### lt +ltr=### ltr +lx=### lx +mkdir=### mkdir +mkcd=### mkcd +poke=### poke +rm=### rm +scrub=### scrub +nav-fns=## 5.2 Navigation +cdi=### cdi +clone=### clone +clonet=### clonet +editors=## 5.3 Editors and Viewers +edit=### edit +fc=### fc +less=### less +rawfish=### rawfish +view=### view +git=## 5.4 Git and Version Control +branch=### branch +gi=### gi +gitignore=### gi +git-clean=### git-clean +gitup=### gitup +gitui=### gitui +hist=### hist +pkg=### pkg +package=### pkg +package-manager=## 5.5 Package Management +packages=## 5.5 Package Management +search=### search +upgrade=### upgrade +cleanup=### cleanup +parur=### parur +deps=## 5.6 Dependency Management +fish-deps=### fish-deps +check-deps=### check_fish_deps +system=## 5.7 System and Monitoring +top=### top +swapstat=### swapstat +sbver=### sbver +ports=### ports +screensleep=### screensleep +lock=### lock +sudo-toggle=### sudo-toggle +limine=### limine-edit +terminal-mgmt=## 5.8 Terminal Management +tab=### tab +split=### split +spwin=### spwin +detach=### detach +bkg=### bkg +ssh=### ssh +clipboard=## 5.9 Clipboard +copy-fn=### y +paste=### paste +network=## 5.10 Network +gip=### gip +ping=### ping +qr=### qr +logging=## 5.11 Pager and Logging +logs=### logs +smart-exit=### smart_exit +ai=## 5.12 AI and Developer Tools +antigravity=### antigravity +claude=### claude-resume +claude-docs=### claude-docs +claude-pr=### claude-pr +code-resume=### code-resume +superpowers=### superpowers +media=## 5.13 Media and Utilities +dng2avif=### dng2avif +spark=### spark +miscfns=## 5.14 Miscellaneous +bash=### bash +cheat=### cheat +dockup=### dockup +joplin=### joplin +replay=### replay +tmux=### tmux-clean +wake-lock=### wake-lock +zellij=### zellij + +# ── Section 6: Dependency Catalog ──────────────────────────── +catalog=# 6. DEPENDENCY CATALOG +deps-catalog=# 6. DEPENDENCY CATALOG +required=## Required +integrations=## Integrations +recommended=## Recommended +install-methods=## Install Methods + +# ── Section 7: Customization ────────────────────────────────── +customization=# 7. CUSTOMIZATION +customize=# 7. CUSTOMIZATION +local=## Machine-local Configuration +secrets=## Secrets and API Keys +overrides=## Overriding Configuration Variables +universal=## Fish Universal Variables + +# ── Section 8: Fisher Plugins ───────────────────────────────── +plugins=# 8. FISHER PLUGINS +fisher=# 8. FISHER PLUGINS + +# ── Section 9: Viewing This Manual ─────────────────────────── +viewing=# 9. VIEWING THIS MANUAL +manual=# 9. VIEWING THIS MANUAL +ov=## With ov (recommended) +man-page=## As a man page (if compiled) +manpage=## As a man page (if compiled) +jump=## Jumping to a section diff --git a/docs/fish-config.md b/docs/fish-config.md index e736255..1c7dd42 100644 --- a/docs/fish-config.md +++ b/docs/fish-config.md @@ -1216,7 +1216,16 @@ calls fisher update as its first step. config_help ov renders the Markdown with syntax highlighting and section-based -navigation. Use , and . to jump between sections. Press / to search. +navigation. + + Space next section + ^ previous section + Alt+u toggle section list sidebar + / search forward + n / N next / previous search match + g go to line number + j interactive jump target (line, %, or 'section') + q quit ## With bat diff --git a/functions/config_help.fish b/functions/config_help.fish index 5901028..6e58232 100644 --- a/functions/config_help.fish +++ b/functions/config_help.fish @@ -8,7 +8,11 @@ # Opens the offline fish shell configuration manual in the best available # pager. Falls back through ov -> bat -> man -> less -> cat. # If a section keyword is provided, the pager opens at the first heading -# that matches the keyword (case-insensitive). +# that matches the keyword. Lookup order: docs/fish-config.index (exact +# keyword aliases), then a normalized heading scan as fallback. +# When jumping to a section the file is sliced from that line onwards so +# ov never has to search through section-header lines (which --section-header +# pins and hides from pattern matching). # # ARGUMENTS # section Optional keyword to jump to a matching section heading @@ -24,6 +28,7 @@ # config_help fish-deps function config_help --description 'Open the offline fish shell configuration manual' set -l doc_file "$__fish_config_dir/docs/fish-config.md" + set -l idx_file "$__fish_config_dir/docs/fish-config.index" set -l man_file "$__fish_config_dir/docs/fish-config.1" if not test -f "$doc_file" @@ -34,11 +39,47 @@ function config_help --description 'Open the offline fish shell configuration ma end # ── Resolve section start line ─────────────────────────────── + # 1. Look up keyword in fish-config.index (keyword → exact heading text). + # 2. Fall back to normalized scan of heading lines if not in index. + # 3. Resolve start_line via grep -F on the heading text (immune to line + # number drift — only breaks if the heading itself is renamed). set -l start_line 1 if test -n "$argv[1]" - set -l found (grep -n -im 1 "^#\+.*$argv[1]" "$doc_file" | cut -d: -f1) - if test -n "$found" - set start_line $found + set -l norm_kw (string lower -- $argv[1] | string replace -ra '[^a-z0-9]' '') + set -l found_text "" + + # ── Index lookup ───────────────────────────────────────── + if test -f "$idx_file" + while read -l idxline + string match -qr '^[[:space:]]*(#|$)' -- $idxline; and continue + set -l kv (string split -m 1 '=' -- $idxline) + test (count $kv) -lt 2; and continue + set -l k (string lower -- $kv[1] | string replace -ra '[^a-z0-9]' '') + if test "$k" = "$norm_kw" + set found_text $kv[2] + break + end + end < "$idx_file" + end + + # ── Normalized scan fallback ───────────────────────────── + if test -z "$found_text" + for entry in (grep -n "^#" "$doc_file") + set -l parts (string split -m 1 ':' -- $entry) + set -l text $parts[2] + set -l norm_text (string lower -- $text | string replace -ra '[^a-z0-9]' '') + if string match -q "*$norm_kw*" $norm_text + set found_text $text + break + end + end + end + + if test -n "$found_text" + set -l lnum (grep -Fn "$found_text" "$doc_file" | cut -d: -f1 | head -1) + if test -n "$lnum" + set start_line $lnum + end else set_color yellow echo "note: no section matching '$argv[1]' — opening at top" >&2 @@ -47,23 +88,46 @@ function config_help --description 'Open the offline fish shell configuration ma end # ── Viewer fallback chain ──────────────────────────────────── - if type -q ov - ov --syntax --syntax-name markdown \ - --section-delimiter "^#" \ - --section-header \ - +"$start_line" "$doc_file" + # When jumping to a section, slice the file from start_line so ov + # opens with that section at the top without needing --pattern. + # --pattern on section-delimiter lines is unreliable: --section-header + # pins those lines as sticky headers, removing them from search scope. + # Section nav: Space (next), ^ (previous), Alt+u (section list sidebar). + if type -q ov; and type -q bat + set -l ov_args \ + --section-delimiter "^#" \ + --section-header + if test $start_line -gt 1 + bat --color=always --style=plain --language=markdown "$doc_file" \ + | tail -n +$start_line \ + | ov $ov_args + else + bat --color=always --style=plain --language=markdown "$doc_file" \ + | ov $ov_args + end + # ov alone: section navigation on raw Markdown; no code highlighting. + else if type -q ov + set -l ov_args \ + --section-delimiter "^#" \ + --section-header + if test $start_line -gt 1 + tail -n +$start_line "$doc_file" | ov $ov_args + else + ov $ov_args "$doc_file" + end + + # bat alone: syntax highlighting with built-in paging; no line jump. else if type -q bat if test $start_line -gt 1 - # bat can't jump to a line in paging mode; show a hint instead set_color brblack - echo "note: bat pager active — use / to search for your section" >&2 + echo "note: bat pager — use / to search for your section" >&2 set_color normal end bat --language=markdown --paging=always "$doc_file" + # Pre-compiled man page (generated by CI after merge). else if test -f "$man_file" - # Pre-compiled man page as a pager-independent fallback man -l "$man_file" else if type -q less From cb4d74423a45faf0fefb893119971a2ae1371b3b Mon Sep 17 00:00:00 2001 From: rootiest Date: Sat, 6 Jun 2026 04:16:13 -0400 Subject: [PATCH 3/4] feat(config_help): add --help flag and persistent nav hint header - config_help --help / -h prints full usage, section keyword examples, ov navigation key reference, and the pager fallback chain. - Prepend a dim nav hint line to the ov input stream and pin it with --header 1 so "Space=next section ^=prev Alt+u=sections /=search q=quit" is always visible at the top of the screen. --- functions/config_help.fish | 90 +++++++++++++++++++++++++++++++------- 1 file changed, 75 insertions(+), 15 deletions(-) diff --git a/functions/config_help.fish b/functions/config_help.fish index 6e58232..a36c72e 100644 --- a/functions/config_help.fish +++ b/functions/config_help.fish @@ -3,6 +3,7 @@ # SYNOPSIS # config_help [section] +# config_help --help # # DESCRIPTION # Opens the offline fish shell configuration manual in the best available @@ -10,15 +11,16 @@ # If a section keyword is provided, the pager opens at the first heading # that matches the keyword. Lookup order: docs/fish-config.index (exact # keyword aliases), then a normalized heading scan as fallback. -# When jumping to a section the file is sliced from that line onwards so -# ov never has to search through section-header lines (which --section-header -# pins and hides from pattern matching). +# When opened with ov a sticky navigation hint is shown at the top of the +# screen. Pass --help or -h to print usage and navigation key reference. # # ARGUMENTS -# section Optional keyword to jump to a matching section heading +# section Optional keyword to jump to a matching section heading +# --help Print usage and navigation reference, then exit +# -h Alias for --help # # RETURNS -# 0 Manual displayed +# 0 Manual displayed (or --help printed) # 1 Documentation file not found # # EXAMPLE @@ -26,7 +28,48 @@ # config_help keybindings # config_help pkg # config_help fish-deps +# config_help --help function config_help --description 'Open the offline fish shell configuration manual' + # ── --help / -h ────────────────────────────────────────────── + if contains -- --help $argv; or contains -- -h $argv + echo "config_help — view the offline fish shell configuration manual" + echo "" + echo "USAGE" + echo " config_help [section]" + echo " config_help --help" + echo "" + echo "ARGUMENTS" + echo " section Optional keyword to jump to a matching section heading." + echo " Searches docs/fish-config.index for aliases first, then" + echo " falls back to a normalized (case- and punctuation-insensitive)" + echo " scan of heading lines." + echo "" + echo "EXAMPLES" + echo " config_help open at top" + echo " config_help keybindings jump to Key Bindings section" + echo " config_help pkg jump to the pkg function entry" + echo " config_help fish-deps jump to fish-deps" + echo " config_help abbreviations jump to Abbreviations section" + echo "" + echo "NAVIGATION (ov pager)" + echo " Space next section" + echo " ^ previous section" + echo " Alt+u toggle section list sidebar" + echo " / search forward" + echo " n / N next / previous search match" + echo " g go to line number" + echo " q quit" + echo "" + echo "PAGER FALLBACK CHAIN" + echo " 1. ov + bat section nav + syntax highlighting (best)" + echo " 2. ov alone section nav, raw Markdown" + echo " 3. bat alone syntax highlighting, use / to search" + echo " 4. man -l pre-compiled man page (if available)" + echo " 5. less plain text with line-jump" + echo " 6. cat plain output" + return 0 + end + set -l doc_file "$__fish_config_dir/docs/fish-config.md" set -l idx_file "$__fish_config_dir/docs/fish-config.index" set -l man_file "$__fish_config_dir/docs/fish-config.1" @@ -87,34 +130,51 @@ function config_help --description 'Open the offline fish shell configuration ma end end + # ── Navigation hint line ───────────────────────────────────── + # Prepended to the ov input stream and pinned via --header 1 so it + # remains visible at the top of the screen at all times. + set -l nav_hint \ + " \033[2m[ Space=next section ^=prev Alt+u=sections /=search q=quit ]\033[0m" + # ── Viewer fallback chain ──────────────────────────────────── # When jumping to a section, slice the file from start_line so ov # opens with that section at the top without needing --pattern. - # --pattern on section-delimiter lines is unreliable: --section-header - # pins those lines as sticky headers, removing them from search scope. - # Section nav: Space (next), ^ (previous), Alt+u (section list sidebar). + # (--section-header pins delimiter lines as sticky headers, removing + # them from pattern-search scope — tail-slice sidesteps this entirely.) if type -q ov; and type -q bat set -l ov_args \ + --header 1 \ --section-delimiter "^#" \ --section-header if test $start_line -gt 1 - bat --color=always --style=plain --language=markdown "$doc_file" \ - | tail -n +$start_line \ - | ov $ov_args + begin + printf "$nav_hint\n" + bat --color=always --style=plain --language=markdown "$doc_file" \ + | tail -n +$start_line + end | ov $ov_args else - bat --color=always --style=plain --language=markdown "$doc_file" \ - | ov $ov_args + begin + printf "$nav_hint\n" + bat --color=always --style=plain --language=markdown "$doc_file" + end | ov $ov_args end # ov alone: section navigation on raw Markdown; no code highlighting. else if type -q ov set -l ov_args \ + --header 1 \ --section-delimiter "^#" \ --section-header if test $start_line -gt 1 - tail -n +$start_line "$doc_file" | ov $ov_args + begin + printf "$nav_hint\n" + tail -n +$start_line "$doc_file" + end | ov $ov_args else - ov $ov_args "$doc_file" + begin + printf "$nav_hint\n" + cat "$doc_file" + end | ov $ov_args end # bat alone: syntax highlighting with built-in paging; no line jump. From ba92267a8044e06bde8b4a79b868e4b845446569 Mon Sep 17 00:00:00 2001 From: rootiest Date: Sat, 6 Jun 2026 04:18:04 -0400 Subject: [PATCH 4/4] feat(config_help): colorize --help output Section headers in bold blue, argument/flag names in yellow, command examples in green, navigation keys in cyan, fallback chain numbers dimmed. All reset to normal after each colored span. --- functions/config_help.fish | 73 ++++++++++++++++++++++---------------- 1 file changed, 43 insertions(+), 30 deletions(-) diff --git a/functions/config_help.fish b/functions/config_help.fish index a36c72e..bf03721 100644 --- a/functions/config_help.fish +++ b/functions/config_help.fish @@ -32,41 +32,54 @@ function config_help --description 'Open the offline fish shell configuration manual' # ── --help / -h ────────────────────────────────────────────── if contains -- --help $argv; or contains -- -h $argv - echo "config_help — view the offline fish shell configuration manual" + set_color --bold + echo config_help + set_color normal + echo " — view the offline fish shell configuration manual" echo "" - echo "USAGE" - echo " config_help [section]" - echo " config_help --help" + set_color --bold brblue + echo USAGE + set_color normal + echo " config_help "(set_color yellow)"[section]"(set_color normal) + echo " config_help "(set_color yellow)"--help"(set_color normal) echo "" - echo "ARGUMENTS" - echo " section Optional keyword to jump to a matching section heading." + set_color --bold brblue + echo ARGUMENTS + set_color normal + echo " "(set_color yellow)"section"(set_color normal)" Optional keyword to jump to a matching section heading." echo " Searches docs/fish-config.index for aliases first, then" echo " falls back to a normalized (case- and punctuation-insensitive)" echo " scan of heading lines." echo "" - echo "EXAMPLES" - echo " config_help open at top" - echo " config_help keybindings jump to Key Bindings section" - echo " config_help pkg jump to the pkg function entry" - echo " config_help fish-deps jump to fish-deps" - echo " config_help abbreviations jump to Abbreviations section" + set_color --bold brblue + echo EXAMPLES + set_color normal + echo " "(set_color green)"config_help"(set_color normal)" open at top" + echo " "(set_color green)"config_help keybindings"(set_color normal)" jump to Key Bindings section" + echo " "(set_color green)"config_help pkg"(set_color normal)" jump to the pkg function entry" + echo " "(set_color green)"config_help fish-deps"(set_color normal)" jump to fish-deps" + echo " "(set_color green)"config_help abbreviations"(set_color normal)" jump to Abbreviations section" echo "" + set_color --bold brblue echo "NAVIGATION (ov pager)" - echo " Space next section" - echo " ^ previous section" - echo " Alt+u toggle section list sidebar" - echo " / search forward" - echo " n / N next / previous search match" - echo " g go to line number" - echo " q quit" + set_color normal + echo " "(set_color cyan)"Space"(set_color normal)" next section" + echo " "(set_color cyan)"^"(set_color normal)" previous section" + echo " "(set_color cyan)"Alt+u"(set_color normal)" toggle section list sidebar" + echo " "(set_color cyan)"/"(set_color normal)" search forward" + echo " "(set_color cyan)"n"(set_color normal)" / "(set_color cyan)"N"(set_color normal)" next / previous search match" + echo " "(set_color cyan)"g"(set_color normal)" go to line number" + echo " "(set_color cyan)"q"(set_color normal)" quit" echo "" + set_color --bold brblue echo "PAGER FALLBACK CHAIN" - echo " 1. ov + bat section nav + syntax highlighting (best)" - echo " 2. ov alone section nav, raw Markdown" - echo " 3. bat alone syntax highlighting, use / to search" - echo " 4. man -l pre-compiled man page (if available)" - echo " 5. less plain text with line-jump" - echo " 6. cat plain output" + set_color normal + echo " "(set_color brblack)"1."(set_color normal)" ov + bat section nav + syntax highlighting "(set_color brblack)"(best)"(set_color normal) + echo " "(set_color brblack)"2."(set_color normal)" ov alone section nav, raw Markdown" + echo " "(set_color brblack)"3."(set_color normal)" bat alone syntax highlighting, use / to search" + echo " "(set_color brblack)"4."(set_color normal)" man -l pre-compiled man page (if available)" + echo " "(set_color brblack)"5."(set_color normal)" less plain text with line-jump" + echo " "(set_color brblack)"6."(set_color normal)" cat plain output" return 0 end @@ -102,7 +115,7 @@ function config_help --description 'Open the offline fish shell configuration ma set found_text $kv[2] break end - end < "$idx_file" + end <"$idx_file" end # ── Normalized scan fallback ───────────────────────────── @@ -134,7 +147,7 @@ function config_help --description 'Open the offline fish shell configuration ma # Prepended to the ov input stream and pinned via --header 1 so it # remains visible at the top of the screen at all times. set -l nav_hint \ - " \033[2m[ Space=next section ^=prev Alt+u=sections /=search q=quit ]\033[0m" + " \033[2mNAVIGATION: [ Space=next section ^=prev Alt+u=sections /=search q=quit ]\033[0m" # ── Viewer fallback chain ──────────────────────────────────── # When jumping to a section, slice the file from start_line so ov @@ -159,7 +172,7 @@ function config_help --description 'Open the offline fish shell configuration ma end | ov $ov_args end - # ov alone: section navigation on raw Markdown; no code highlighting. + # ov alone: section navigation on raw Markdown; no code highlighting. else if type -q ov set -l ov_args \ --header 1 \ @@ -177,7 +190,7 @@ function config_help --description 'Open the offline fish shell configuration ma end | ov $ov_args end - # bat alone: syntax highlighting with built-in paging; no line jump. + # bat alone: syntax highlighting with built-in paging; no line jump. else if type -q bat if test $start_line -gt 1 set_color brblack @@ -186,7 +199,7 @@ function config_help --description 'Open the offline fish shell configuration ma end bat --language=markdown --paging=always "$doc_file" - # Pre-compiled man page (generated by CI after merge). + # Pre-compiled man page (generated by CI after merge). else if test -f "$man_file" man -l "$man_file"