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