diff --git a/.gitea/workflows/build-docs.yml b/.gitea/workflows/build-docs.yml index 7b3cab8..0a5ad63 100644 --- a/.gitea/workflows/build-docs.yml +++ b/.gitea/workflows/build-docs.yml @@ -35,11 +35,14 @@ jobs: docs/fish-config.md \ -o docs/html/ + - name: Generate wiki markdown + run: python3 docs/split-wiki.py + - name: Commit generated docs run: | git config user.name "Gitea Actions" git config user.email "actions@gitea" - git add docs/fish-config.1 docs/html/ + git add docs/fish-config.1 docs/html/ docs/wiki/ git diff --cached --quiet && echo "No changes to commit" && exit 0 - git commit -m "chore(docs): regenerate man page and HTML docs" + git commit -m "chore(docs): regenerate man page, HTML docs, and wiki" git push diff --git a/README.md b/README.md index 96eb59e..f3f8a76 100644 --- a/README.md +++ b/README.md @@ -322,30 +322,16 @@ rm -f file.txt # Falls through to standard rm -f ### 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). +Full documentation lives in [`docs/wiki/`](docs/wiki/index.md) — a multi-page Markdown wiki auto-generated from the single source file `docs/fish-config.md` on every push to `main`. | Command | Description | |---|---| -| `help config` | Open the offline manual in the best available pager | +| `help config` | Open the terminal manual in the best available pager | | `help config ` | Jump directly to a section matching the keyword | | `config-help --html` | Open the pre-built HTML docs in the default browser | | `config-help --man` | Open the compiled man page via `man -l` | -The pager viewer falls back through: **ov** (syntax highlight + section navigation) → **bat** (syntax highlight) → **man -l** (pre-compiled man page) → **less** → **cat**. - -Examples: `help config keybindings` · `help config pkg` · `help config fish-deps` · `help config abbreviations` - -> **Tip:** `help config` is the preferred way to access offline docs — it integrates naturally with fish's built-in `help` command. The underlying `config-help` function is still available directly if needed. - -The `--html` flag opens `docs/html/index.html` in your default browser. It detects the correct browser by querying the system's `https://` scheme handler (via `xdg-mime`), falling back through known browser binaries, then `xdg-open` as a last resort. Set `$fish_help_browser` or `$BROWSER` to override. - -You can also read the documentation as a standard man page — the symlink and `MANPATH` are set up automatically on shell start: - -```fish -man fish-config -``` - -The man page is auto-generated from `docs/fish-config.md` by the CI pipeline on every push to `main`. +The pager falls back through: **ov** → **bat** → **man -l** → **less** → **cat**. > **Note:** `fish-config` (hyphen) is this configuration's man page. `fish_config` (underscore) is fish's built-in browser-based configuration tool — a completely separate command. Don't mix them up. diff --git a/docs/fish-config.md b/docs/fish-config.md index 497a648..e539fe4 100644 --- a/docs/fish-config.md +++ b/docs/fish-config.md @@ -1314,6 +1314,15 @@ find the real browser binary, then falls back through known browser binaries (firefox, chromium, vivaldi, etc.), and finally xdg-open as a last resort. Set $fish_help_browser or $BROWSER to override. +## As a wiki + +The generated Markdown wiki lives in docs/wiki/. index.md provides the +project overview and a full table of contents. Each section page has a +navigation bar at the top linking to every other section. + +The wiki is auto-generated from this file by the CI pipeline on every +push to main that changes docs/fish-config.md. + ## Jumping to a section help config keybindings diff --git a/docs/split-wiki.py b/docs/split-wiki.py new file mode 100644 index 0000000..dd727c6 --- /dev/null +++ b/docs/split-wiki.py @@ -0,0 +1,115 @@ +#!/usr/bin/env python3 +"""Split docs/fish-config.md into a multi-page Markdown wiki in docs/wiki/. + +Index page: docs/wiki/index.md — DESCRIPTION intro + full ToC +Section pages: docs/wiki/-.md — one per numbered section, + with a top-level nav bar linking to every other section. +""" + +import re +import sys +from pathlib import Path + +# Sections whose content is merged into the index intro. +INTRO_TITLES = {"NAME", "SYNOPSIS", "DESCRIPTION"} + +# Sections that are skipped entirely (replaced by the generated ToC). +SKIP_TITLES = {"TABLE OF CONTENTS"} + + +def strip_front_matter(text: str) -> str: + """Remove pandoc YAML front matter (--- ... ---) from the start.""" + if text.startswith("---"): + end = text.index("\n---\n", 3) + 5 + return text[end:] + return text + + +def slugify(title: str) -> str: + """Convert a section title to a kebab-case filename slug.""" + s = title.lower() + s = re.sub(r"[^\w\s-]", "", s) + s = re.sub(r"[\s_]+", "-", s).strip("-") + return s + + +def build_nav(sections: list, current_filename: str | None = None) -> str: + """Return a one-line navigation bar for a section page.""" + parts = ["[Index](index.md)"] + for s in sections: + label = s["title"].title() + if s["filename"] == current_filename: + parts.append(f"**{label}**") + else: + parts.append(f"[{label}]({s['filename']})") + return "**Sections:** " + " | ".join(parts) + + +def build_full_toc(sections: list) -> str: + """Return a Markdown ToC list for the index page.""" + lines = ["## Table of Contents", ""] + for s in sections: + lines.append(f"- [{s['title'].title()}]({s['filename']})") + return "\n".join(lines) + + +def main() -> None: + src = Path("docs/fish-config.md") + out_dir = Path("docs/wiki") + + if not src.exists(): + print(f"error: {src} not found", file=sys.stderr) + sys.exit(1) + + out_dir.mkdir(parents=True, exist_ok=True) + + text = strip_front_matter(src.read_text()) + + # Split on level-1 headings; re.split keeps the delimiters. + parts = re.split(r"^(# .+)$", text, flags=re.MULTILINE) + # parts[0] — text before first heading (empty after front-matter strip) + # parts[1,3,…] — headings + # parts[2,4,…] — body content after each heading + + raw_sections = [] + for i in range(1, len(parts), 2): + heading = parts[i].strip() + body = parts[i + 1] if i + 1 < len(parts) else "" + title = heading[2:].strip() # strip leading '# ' + raw_sections.append({"heading": heading, "title": title, "body": body}) + + intro_parts = [] + numbered_sections = [] + for s in raw_sections: + if s["title"] in INTRO_TITLES: + if s["title"] == "DESCRIPTION": + intro_parts.append(s["body"].strip()) + elif s["title"] in SKIP_TITLES: + pass # discard; ToC is auto-generated + else: + slug = slugify(s["title"]) + s["filename"] = f"{slug}.md" + numbered_sections.append(s) + + # ── Write index.md ────────────────────────────────────────────────────── + intro_body = "\n\n".join(intro_parts) + toc = build_full_toc(numbered_sections) + index_content = f"# Fish Shell Configuration\n\n{intro_body}\n\n---\n\n{toc}\n" + (out_dir / "index.md").write_text(index_content) + print(" wrote docs/wiki/index.md") + + # ── Write section pages ────────────────────────────────────────────────── + for s in numbered_sections: + nav = build_nav(numbered_sections, current_filename=s["filename"]) + page_content = ( + f"{s['heading']}\n\n" + f"{nav}\n\n" + f"---\n\n" + f"{s['body'].strip()}\n" + ) + (out_dir / s["filename"]).write_text(page_content) + print(f" wrote docs/wiki/{s['filename']}") + + +if __name__ == "__main__": + main() diff --git a/docs/wiki/1-configuration-variables.md b/docs/wiki/1-configuration-variables.md new file mode 100644 index 0000000..25b974f --- /dev/null +++ b/docs/wiki/1-configuration-variables.md @@ -0,0 +1,51 @@ +# 1. CONFIGURATION VARIABLES + +**Sections:** [Index](index.md) | **1. Configuration Variables** | [2. Path Setup](2-path-setup.md) | [3. Key Bindings](3-key-bindings.md) | [4. Abbreviations](4-abbreviations.md) | [5. Functions Reference](5-functions-reference.md) | [6. Dependency Catalog](6-dependency-catalog.md) | [7. Customization](7-customization.md) | [8. Fisher Plugins](8-fisher-plugins.md) | [9. Viewing This Manual](9-viewing-this-manual.md) + +--- + +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 ~ + +--- diff --git a/docs/wiki/2-path-setup.md b/docs/wiki/2-path-setup.md new file mode 100644 index 0000000..69ef752 --- /dev/null +++ b/docs/wiki/2-path-setup.md @@ -0,0 +1,22 @@ +# 2. PATH SETUP + +**Sections:** [Index](index.md) | [1. Configuration Variables](1-configuration-variables.md) | **2. Path Setup** | [3. Key Bindings](3-key-bindings.md) | [4. Abbreviations](4-abbreviations.md) | [5. Functions Reference](5-functions-reference.md) | [6. Dependency Catalog](6-dependency-catalog.md) | [7. Customization](7-customization.md) | [8. Fisher Plugins](8-fisher-plugins.md) | [9. Viewing This Manual](9-viewing-this-manual.md) + +--- + +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. + +--- diff --git a/docs/wiki/3-key-bindings.md b/docs/wiki/3-key-bindings.md new file mode 100644 index 0000000..e4ad613 --- /dev/null +++ b/docs/wiki/3-key-bindings.md @@ -0,0 +1,49 @@ +# 3. KEY BINDINGS + +**Sections:** [Index](index.md) | [1. Configuration Variables](1-configuration-variables.md) | [2. Path Setup](2-path-setup.md) | **3. Key Bindings** | [4. Abbreviations](4-abbreviations.md) | [5. Functions Reference](5-functions-reference.md) | [6. Dependency Catalog](6-dependency-catalog.md) | [7. Customization](7-customization.md) | [8. Fisher Plugins](8-fisher-plugins.md) | [9. Viewing This Manual](9-viewing-this-manual.md) + +--- + +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 + +--- diff --git a/docs/wiki/4-abbreviations.md b/docs/wiki/4-abbreviations.md new file mode 100644 index 0000000..7be5e09 --- /dev/null +++ b/docs/wiki/4-abbreviations.md @@ -0,0 +1,146 @@ +# 4. ABBREVIATIONS + +**Sections:** [Index](index.md) | [1. Configuration Variables](1-configuration-variables.md) | [2. Path Setup](2-path-setup.md) | [3. Key Bindings](3-key-bindings.md) | **4. Abbreviations** | [5. Functions Reference](5-functions-reference.md) | [6. Dependency Catalog](6-dependency-catalog.md) | [7. Customization](7-customization.md) | [8. Fisher Plugins](8-fisher-plugins.md) | [9. Viewing This Manual](9-viewing-this-manual.md) + +--- + +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 + +--- diff --git a/docs/wiki/5-functions-reference.md b/docs/wiki/5-functions-reference.md new file mode 100644 index 0000000..62f6bf8 --- /dev/null +++ b/docs/wiki/5-functions-reference.md @@ -0,0 +1,808 @@ +# 5. FUNCTIONS REFERENCE + +**Sections:** [Index](index.md) | [1. Configuration Variables](1-configuration-variables.md) | [2. Path Setup](2-path-setup.md) | [3. Key Bindings](3-key-bindings.md) | [4. Abbreviations](4-abbreviations.md) | **5. Functions Reference** | [6. Dependency Catalog](6-dependency-catalog.md) | [7. Customization](7-customization.md) | [8. Fisher Plugins](8-fisher-plugins.md) | [9. Viewing This Manual](9-viewing-this-manual.md) + +--- + +## 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 + +### config-help + + Synopsis: config-help [SECTION] + config-help --html + config-help --man + config-help -h | --help + + Opens the offline fish shell configuration manual. Without flags, opens + the Markdown source in the best available pager (ov > bat > man > less > + cat). If SECTION is given, jumps to the first heading matching that + keyword (case-insensitive; checks fish-config.index aliases first). + + Flags: + --html / -w Open docs/html/index.html in the default browser. + Detects the browser via xdg-mime x-scheme-handler/https, + then known binaries, then xdg-open as last resort. + Respects $fish_help_browser and $BROWSER. + --man / -m Open docs/fish-config.1 via man -l directly. + --help / -h Print usage and navigation key reference. + + config-help keybindings + config-help pkg + config-help --html + config-help --man + +### config-update + + Synopsis: config-update [-h] [-n] [-f] + + Pulls the latest fish configuration from the upstream repository + (https://git.rootiest.dev/rootiest/fish-config.git) into ~/.config/fish. + The remote URL is hard-coded, so this works on fresh clones with no git + remote configured. All git output is suppressed; colored messages report + fetch and merge status. After a successful pull, run `exec fish` to + reload. + + Flags: + --dry-run / -n Fetch and show available commits without applying them. + --force / -f Stash local changes, pull, then restore the stash. + --help / -h Show usage. + + config-update + config-update --dry-run + config-update --force + +### 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. + +--- diff --git a/docs/wiki/6-dependency-catalog.md b/docs/wiki/6-dependency-catalog.md new file mode 100644 index 0000000..6bf5a2b --- /dev/null +++ b/docs/wiki/6-dependency-catalog.md @@ -0,0 +1,56 @@ +# 6. DEPENDENCY CATALOG + +**Sections:** [Index](index.md) | [1. Configuration Variables](1-configuration-variables.md) | [2. Path Setup](2-path-setup.md) | [3. Key Bindings](3-key-bindings.md) | [4. Abbreviations](4-abbreviations.md) | [5. Functions Reference](5-functions-reference.md) | **6. Dependency Catalog** | [7. Customization](7-customization.md) | [8. Fisher Plugins](8-fisher-plugins.md) | [9. Viewing This Manual](9-viewing-this-manual.md) + +--- + +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 + +--- diff --git a/docs/wiki/7-customization.md b/docs/wiki/7-customization.md new file mode 100644 index 0000000..d3dbbfd --- /dev/null +++ b/docs/wiki/7-customization.md @@ -0,0 +1,40 @@ +# 7. CUSTOMIZATION + +**Sections:** [Index](index.md) | [1. Configuration Variables](1-configuration-variables.md) | [2. Path Setup](2-path-setup.md) | [3. Key Bindings](3-key-bindings.md) | [4. Abbreviations](4-abbreviations.md) | [5. Functions Reference](5-functions-reference.md) | [6. Dependency Catalog](6-dependency-catalog.md) | **7. Customization** | [8. Fisher Plugins](8-fisher-plugins.md) | [9. Viewing This Manual](9-viewing-this-manual.md) + +--- + +## 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. + +--- diff --git a/docs/wiki/8-fisher-plugins.md b/docs/wiki/8-fisher-plugins.md new file mode 100644 index 0000000..81d38c2 --- /dev/null +++ b/docs/wiki/8-fisher-plugins.md @@ -0,0 +1,32 @@ +# 8. FISHER PLUGINS + +**Sections:** [Index](index.md) | [1. Configuration Variables](1-configuration-variables.md) | [2. Path Setup](2-path-setup.md) | [3. Key Bindings](3-key-bindings.md) | [4. Abbreviations](4-abbreviations.md) | [5. Functions Reference](5-functions-reference.md) | [6. Dependency Catalog](6-dependency-catalog.md) | [7. Customization](7-customization.md) | **8. Fisher Plugins** | [9. Viewing This Manual](9-viewing-this-manual.md) + +--- + +Fisher is bootstrapped automatically on the **first interactive session** via +`conf.d/first_run.fish`. This also applies the Catppuccin Mocha theme and +prints a one-time welcome message. Subsequent sessions skip all first-run +logic with zero overhead. + +To re-trigger first-run initialization (e.g., after a fresh install or for +testing), run: + + set -Ue __fish_config_first_run_complete + +Then open a new shell. + +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. + +--- diff --git a/docs/wiki/9-viewing-this-manual.md b/docs/wiki/9-viewing-this-manual.md new file mode 100644 index 0000000..2c84014 --- /dev/null +++ b/docs/wiki/9-viewing-this-manual.md @@ -0,0 +1,59 @@ +# 9. VIEWING THIS MANUAL + +**Sections:** [Index](index.md) | [1. Configuration Variables](1-configuration-variables.md) | [2. Path Setup](2-path-setup.md) | [3. Key Bindings](3-key-bindings.md) | [4. Abbreviations](4-abbreviations.md) | [5. Functions Reference](5-functions-reference.md) | [6. Dependency Catalog](6-dependency-catalog.md) | [7. Customization](7-customization.md) | [8. Fisher Plugins](8-fisher-plugins.md) | **9. Viewing This Manual** + +--- + +## With ov (recommended) + + help config + +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 + + config-help --man + +Opens the compiled docs/fish-config.1 directly via man -l, bypassing +the pager fallback chain. The symlink and MANPATH are also configured +automatically on shell start for the standard invocation: + + man fish-config + +NOTE: fish-config (hyphen) is this config's man page. fish_config +(underscore) is fish's built-in browser-based configuration tool — +a completely separate command. Do not mix them up. + +## In the browser (HTML) + + config-help --html + +Opens docs/html/index.html in the default web browser. Browser detection +queries the system's x-scheme-handler/https MIME entry (via xdg-mime) to +find the real browser binary, then falls back through known browser +binaries (firefox, chromium, vivaldi, etc.), and finally xdg-open as a +last resort. Set $fish_help_browser or $BROWSER to override. + +## Jumping to a section + + help config keybindings + help config abbreviations + help config pkg + help config logs + help config fish-deps + +The keyword is matched case-insensitively against section headings. diff --git a/docs/wiki/index.md b/docs/wiki/index.md new file mode 100644 index 0000000..41713fe --- /dev/null +++ b/docs/wiki/index.md @@ -0,0 +1,38 @@ +# Fish Shell Configuration + +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](1-configuration-variables.md) +- [2. Path Setup](2-path-setup.md) +- [3. Key Bindings](3-key-bindings.md) +- [4. Abbreviations](4-abbreviations.md) +- [5. Functions Reference](5-functions-reference.md) +- [6. Dependency Catalog](6-dependency-catalog.md) +- [7. Customization](7-customization.md) +- [8. Fisher Plugins](8-fisher-plugins.md) +- [9. Viewing This Manual](9-viewing-this-manual.md)