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.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 new file mode 100644 index 0000000..1c7dd42 --- /dev/null +++ b/docs/fish-config.md @@ -0,0 +1,1246 @@ +--- +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. + + 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 + + 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..bf03721 --- /dev/null +++ b/functions/config_help.fish @@ -0,0 +1,212 @@ +# Copyright (C) 2026 Rootiest +# SPDX-License-Identifier: AGPL-3.0-or-later + +# SYNOPSIS +# config_help [section] +# config_help --help +# +# 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. Lookup order: docs/fish-config.index (exact +# keyword aliases), then a normalized heading scan as fallback. +# 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 +# --help Print usage and navigation reference, then exit +# -h Alias for --help +# +# RETURNS +# 0 Manual displayed (or --help printed) +# 1 Documentation file not found +# +# EXAMPLE +# config_help +# 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 + set_color --bold + echo config_help + set_color normal + echo " — view the offline fish shell configuration manual" + echo "" + 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 "" + 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 "" + 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)" + 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" + 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 + + 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" + set_color red + echo "error: documentation not found at $doc_file" >&2 + set_color normal + return 1 + 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 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 + set_color normal + 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[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 + # opens with that section at the top without needing --pattern. + # (--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 + begin + printf "$nav_hint\n" + bat --color=always --style=plain --language=markdown "$doc_file" \ + | tail -n +$start_line + end | ov $ov_args + else + 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 + begin + printf "$nav_hint\n" + tail -n +$start_line "$doc_file" + end | ov $ov_args + else + begin + printf "$nav_hint\n" + cat "$doc_file" + end | ov $ov_args + end + + # 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 + 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" + man -l "$man_file" + + else if type -q less + less +"$start_line" "$doc_file" + + else + cat "$doc_file" + end +end