Gitea Actions
2492 lines
66 KiB
Groff
2492 lines
66 KiB
Groff
.\" Automatically generated by Pandoc 3.1.3
|
|
.\"
|
|
.\" Define V font for inline verbatim, using C font in formats
|
|
.\" that render this, and otherwise B font.
|
|
.ie "\f[CB]x\f[]"x" \{\
|
|
. ftr V B
|
|
. ftr VI BI
|
|
. ftr VB B
|
|
. ftr VBI BI
|
|
.\}
|
|
.el \{\
|
|
. ftr V CR
|
|
. ftr VI CI
|
|
. ftr VB CB
|
|
. ftr VBI CBI
|
|
.\}
|
|
.TH "FISH-CONFIG" "7" "June 2026" "" "Fish Shell Configuration User Manual"
|
|
.hy
|
|
.SH NAME
|
|
.PP
|
|
fish-config - personal fish shell configuration for Fish 4.x with modern
|
|
CLI tool integration
|
|
.SH SYNOPSIS
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
help config [SECTION]
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
Open this manual in the best available pager.
|
|
Optionally jump to a section by keyword:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
help config keybindings
|
|
help config pkg
|
|
help config abbreviations
|
|
help config logs
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
The \f[V]help config\f[R] syntax integrates with fish\[cq]s built-in
|
|
help command.
|
|
The underlying \f[V]config-help\f[R] function is also available
|
|
directly.
|
|
.SH DESCRIPTION
|
|
.PP
|
|
A production-grade Fish shell configuration targeting Fish 4.x.
|
|
It provides:
|
|
.IP \[bu] 2
|
|
Drop-in replacements for common Unix tools (ls, cat, rm, du, ping, less)
|
|
.IP \[bu] 2
|
|
Deep Kitty and WezTerm terminal integration: tab/window/pane management
|
|
from the command line
|
|
.IP \[bu] 2
|
|
Scrollback history snapshots saved to \[ti]/.terminal_history on session
|
|
exit
|
|
.IP \[bu] 2
|
|
Automatic Python virtualenv activation on directory change
|
|
.IP \[bu] 2
|
|
Cross-platform package management via pkg and fish-deps
|
|
.IP \[bu] 2
|
|
AI session helpers for Claude Code and Antigravity
|
|
.IP \[bu] 2
|
|
Catppuccin Mocha color theme throughout
|
|
.PP
|
|
The configuration is split across:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
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
|
|
sponge_privacy.fish Sponge privacy patterns; filters credentials from history
|
|
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
|
|
scripts/
|
|
clean_progress_log.py Renders script(1) typescripts (paru/yay progress
|
|
animations) to clean static logs, preserving color
|
|
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
|
|
* * * * *
|
|
.SH TABLE OF CONTENTS
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
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
|
|
4.11 Shell Aliases
|
|
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. Installation
|
|
10. Personalization
|
|
11. Viewing This Manual
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
* * * * *
|
|
.SH 1. CONFIGURATION VARIABLES
|
|
.PP
|
|
These variables are exported from config.fish on every interactive
|
|
session.
|
|
Override them in \[ti]/.config/.user-dots/fish/local.fish.
|
|
.SS Environment Directories (XDG)
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
XDG_CONFIG_HOME \[ti]/.config
|
|
XDG_CACHE_HOME \[ti]/.cache
|
|
XDG_DATA_HOME \[ti]/.local/share
|
|
XDG_STATE_HOME \[ti]/.local/state
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
Tools that respect XDG are directed to these paths rather than polluting
|
|
$HOME.
|
|
.SS Tool Homes (XDG-compliant)
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
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
|
|
\f[R]
|
|
.fi
|
|
.SS Editor and Pager
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
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)
|
|
\f[R]
|
|
.fi
|
|
.SS Scrollback History
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
SCROLLBACK_HISTORY_DIR \[ti]/.terminal_history
|
|
SCROLLBACK_HISTORY_MAX_FILES 100
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
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 \f[V]logs\f[R] to browse them interactively.
|
|
.SS Other
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
GPG_TTY $(tty) \[em] ensures GPG passphrase prompts work
|
|
CLAUDE_CODE_NO_FLICKER 1 \[em] suppress terminal flicker in Claude Code
|
|
CDPATH . \[ti]/projects \[ti]
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
Opinionated defaults (CDPATH, PAGER/MANPAGER, Vi mode, command shadows,
|
|
terminal integrations) can be switched off per category with universal
|
|
variables \[em] see Section 7, \[lq]Opinionated Components (Minimal
|
|
Mode)\[rq].
|
|
.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/) run the
|
|
command inside a PTY via script(1) so download progress bars are
|
|
preserved on screen, then render the captured terminal animation down to
|
|
a clean static log via scripts/clean_progress_log.py (a small
|
|
terminal-screen emulator that replays cursor movements, collapses
|
|
repainted progress frames to their final state, and preserves ANSI
|
|
color).
|
|
If python3 is unavailable the wrapper falls back to dropping only the
|
|
script(1) header/footer.
|
|
Output is saved 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
|
|
.PP
|
|
Directories prepended to PATH in this order (first wins):
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
\[ti]/.local/bin Standard user-local executables
|
|
\[ti]/Applications User-installed standalone apps
|
|
\[ti]/scripts Personal shell scripts
|
|
\[ti]/bin Cargo binaries (appended \[em] lowest priority)
|
|
$BUN_INSTALL/bin Bun runtime and global packages
|
|
$NPM_CONFIG_PREFIX/bin Global npm packages
|
|
\[ti]/.lmstudio/bin LM Studio CLI
|
|
\[ti]/.resend/bin Resend CLI
|
|
\[ti]/.fzf/bin fzf binary (git-installed)
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
Cargo binaries are intentionally appended (lowest priority) to avoid
|
|
shadowing system-installed Rust tools.
|
|
.PP
|
|
* * * * *
|
|
.SH 3. KEY BINDINGS
|
|
.PP
|
|
The shell uses Vi key bindings (fish_vi_key_bindings).
|
|
All custom bindings are active in Insert, Normal, and Visual modes
|
|
unless noted.
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Binding Action
|
|
─────────────────────────────────────────────────────────────────────
|
|
Ctrl+G Insert the head of the previous command\[aq]s last path
|
|
argument. Equivalent to !$:h in Bash.
|
|
Example: previous = \[dq]cd /usr/local/bin\[dq]
|
|
Ctrl+G inserts \[dq]/usr/local\[dq]
|
|
|
|
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 = \[dq]echo this is a test\[dq]
|
|
type \[dq]this is/that was\[dq], press Ctrl+F
|
|
result = \[dq]echo that was a test\[dq]
|
|
|
|
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: \[dq]mkdir new_folder\[dq] -> \[dq] new_folder\[dq]
|
|
|
|
Ctrl+Alt+= Evaluate the current command line buffer with
|
|
Qalculate! (qalc) and print the result inline.
|
|
Requires qalc to be installed.
|
|
Example: type \[dq]150 * 1.08\[dq], 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.).
|
|
|
|
\[at]\[at] FZF inline picker. Type \[at]\[at] anywhere on the command
|
|
line to open an fzf picker and insert a selection
|
|
at the cursor position.
|
|
\f[R]
|
|
.fi
|
|
.SS FZF Bindings (bundled from PatrickF1/fzf.fish)
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
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
|
|
* * * * *
|
|
.SH 4. ABBREVIATIONS
|
|
.PP
|
|
Abbreviations expand when you press Space or Enter.
|
|
They are terminal-aware: some expand differently in Kitty vs WezTerm vs
|
|
other terminals.
|
|
.SS 4.1 Editors
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
n / nv / neovim nvim
|
|
e edit
|
|
se sudoedit
|
|
k kate
|
|
editt Open new tab with nvim (terminal-aware)
|
|
cdnv cd \[ti]/.config/nvim
|
|
cdnvn cd \[ti]/.config/nvim; nvim
|
|
\f[R]
|
|
.fi
|
|
.SS 4.2 Navigation and Listing
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
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)
|
|
\f[R]
|
|
.fi
|
|
.SS 4.3 Git
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
g git
|
|
lg lazygit
|
|
gitig / git-ignore gi (generate .gitignore)
|
|
\f[R]
|
|
.fi
|
|
.SS 4.4 Terminal Windows, Tabs, and Panes
|
|
.PP
|
|
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.
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
: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)
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
Quick-navigate shortcuts open windows/tabs/panes with preset working
|
|
dirs:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
:tgk New tab at \[ti]/.config/kitty
|
|
:tgn New tab at \[ti]/.config/nvim
|
|
:tgf New tab at \[ti]/.config/fish
|
|
:tgh New tab at \[ti]
|
|
:tgcz New tab at chezmoi source dir
|
|
:tgcm New tab at chezmoi source dir
|
|
:tgp New tab at \[ti]/projects
|
|
:tgr New tab at / (root)
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
Prefixes :wg* and :wvg* / :whg* open OS windows or splits to the same
|
|
set of dirs, respectively.
|
|
.PP
|
|
Prefixes :cd* open tabs with a quick cd shortcut:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
:cdn cd \[ti]/.config/nvim
|
|
:cdf cd \[ti]/.config/fish
|
|
:cdh cd \[ti]
|
|
:cdcz cd to chezmoi source
|
|
:cdp cd \[ti]/projects
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
Appending n to any :cd* abbreviation also runs nvim after changing dir.
|
|
.SS 4.5 Chezmoi
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
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
|
|
\f[R]
|
|
.fi
|
|
.SS 4.6 Docker
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
dcl docker context use default
|
|
dcls docker context ls
|
|
lzd ld (lazydocker)
|
|
\f[R]
|
|
.fi
|
|
.SS 4.7 Systemctl
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
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
|
|
\f[R]
|
|
.fi
|
|
.SS 4.8 AI Assistants
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
ag antigravity
|
|
ag. antigravity .
|
|
v antigravity-ide
|
|
s wezterm ssh (WezTerm only)
|
|
\f[R]
|
|
.fi
|
|
.SS 4.9 History Expansion
|
|
.PP
|
|
These are implemented as keybinding helpers, but can also be typed:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
!\[ha] 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)
|
|
\f[R]
|
|
.fi
|
|
.SS 4.10 Miscellaneous
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
/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
|
|
\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
|
|
.SS 5.1 File and Directory
|
|
.SS cat
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
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 \[ti]/projects/myapp
|
|
\f[R]
|
|
.fi
|
|
.SS copy
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: copy <source> <dest>
|
|
Wraps cp, stripping trailing slashes from source directories to
|
|
prevent unintended nesting inside the destination.
|
|
|
|
copy ./mydir/ \[ti]/backup # copies mydir INTO backup, not backup/mydir/
|
|
\f[R]
|
|
.fi
|
|
.SS du
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
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 \[ti]/Downloads
|
|
du --disk
|
|
\f[R]
|
|
.fi
|
|
.SS dusize
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: dusize [dir]
|
|
Human-readable disk usage for a directory via du -sh. Defaults to cwd.
|
|
|
|
dusize \[ti]/Videos
|
|
\f[R]
|
|
.fi
|
|
.SS lD
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: lD [args...]
|
|
Lists directories only in long format with icons. Uses eza, falls back
|
|
to lsd, then system ls.
|
|
|
|
lD \[ti]/projects
|
|
\f[R]
|
|
.fi
|
|
.SS ls
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: ls [args...]
|
|
Lists files in long format with icons and hyperlinks. Uses eza, falls
|
|
back to lsd, then system ls.
|
|
|
|
ls
|
|
ls -a \[ti]/projects
|
|
\f[R]
|
|
.fi
|
|
.SS lsr
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: lsr [args...]
|
|
Lists files sorted by modification time, oldest first. Uses eza.
|
|
\f[R]
|
|
.fi
|
|
.SS lss
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: lss [args...]
|
|
Lists files sorted by size with gradient color scaling. Uses eza.
|
|
\f[R]
|
|
.fi
|
|
.SS lstree
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: lstree [args...]
|
|
Full recursive tree view with icons. Uses eza.
|
|
|
|
lstree \[ti]/projects/myapp
|
|
\f[R]
|
|
.fi
|
|
.SS lt
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: lt [args...]
|
|
Tree view limited to depth 2 with icons. Uses eza.
|
|
|
|
lt \[ti]/projects
|
|
\f[R]
|
|
.fi
|
|
.SS ltr
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: ltr [args...]
|
|
Lists files sorted by modification time, oldest first, long format with
|
|
age-based gradient scaling. Uses eza.
|
|
\f[R]
|
|
.fi
|
|
.SS lx
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: lx [args...]
|
|
Lists files sorted by extension, long format. Uses eza.
|
|
\f[R]
|
|
.fi
|
|
.SS mkdir
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: mkdir [args...]
|
|
Interactive mkdir that prints a tree of created directories.
|
|
Falls back to mkdir -p silently.
|
|
|
|
mkdir \[ti]/projects/myapp/src
|
|
\f[R]
|
|
.fi
|
|
.SS mkcd
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: mkcd [-s] <dir>
|
|
Creates a directory (including parents) and cd into it. Prints a tree
|
|
of created dirs by default; -s/--silent suppresses output.
|
|
|
|
mkcd \[ti]/projects/newapp/src
|
|
\f[R]
|
|
.fi
|
|
.SS poke
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: poke <file> [file...]
|
|
Creates files via touch, automatically creating any missing parent
|
|
directories first.
|
|
|
|
poke \[ti]/projects/new/src/main.fish
|
|
\f[R]
|
|
.fi
|
|
.SS rm
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
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
|
|
<paths> 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
|
|
\f[R]
|
|
.fi
|
|
.SS rg
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: rg [args...]
|
|
In Kitty, wraps ripgrep with --hyperlink-format=kitty so search
|
|
results are clickable file links in the terminal. Falls back to
|
|
system rg in any other terminal. All other arguments pass through
|
|
unchanged.
|
|
|
|
rg \[dq]fish_greeting\[dq] \[ti]/.config/fish/
|
|
rg -l \[dq]TODO\[dq] \[ti]/projects/myapp
|
|
\f[R]
|
|
.fi
|
|
.SS scrub
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
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
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
* * * * *
|
|
.SS 5.2 Navigation
|
|
.SS cdi
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: cdi [query]
|
|
Interactive directory picker combining zoxide frecency with fzf.
|
|
Equivalent to zi.
|
|
|
|
cdi myproject
|
|
\f[R]
|
|
.fi
|
|
.SS clone
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: clone [args...]
|
|
Clone a git repository into a new Kitty window. Kitty-only.
|
|
|
|
clone https://github.com/user/repo.git
|
|
\f[R]
|
|
.fi
|
|
.SS clonet
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: clonet [args...]
|
|
Clone a git repository into a new Kitty tab. Kitty-only.
|
|
|
|
clonet https://github.com/user/repo.git
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
* * * * *
|
|
.SS 5.3 Editors and Viewers
|
|
.SS edit
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: edit [args...]
|
|
Opens files in nvim. Falls back to $EDITOR, nano, vi.
|
|
|
|
edit \[ti]/.config/fish/config.fish
|
|
\f[R]
|
|
.fi
|
|
.SS fc
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
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
|
|
\f[R]
|
|
.fi
|
|
.SS less
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: less [args...]
|
|
Pager wrapper with fallback chain: $PAGER -> ov -> less -> more -> cat.
|
|
|
|
less /var/log/syslog
|
|
\f[R]
|
|
.fi
|
|
.SS rawfish
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
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.
|
|
\f[R]
|
|
.fi
|
|
.SS view
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: view [args...]
|
|
Opens files in nvim read-only mode (-R). Falls back to less.
|
|
|
|
view /etc/fstab
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
* * * * *
|
|
.SS 5.4 Git and Version Control
|
|
.SS branch
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: branch <branch_name>
|
|
Switches to a local branch, or creates it if it does not exist.
|
|
|
|
branch feature/new-ui
|
|
\f[R]
|
|
.fi
|
|
.SS gi
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
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
|
|
\f[R]
|
|
.fi
|
|
.SS git-clean
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
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
|
|
\f[R]
|
|
.fi
|
|
.SS gitup
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: gitup [args...]
|
|
Fetches updates from the remote and shows git status. Extra args are
|
|
forwarded to git fetch.
|
|
|
|
gitup
|
|
gitup --all
|
|
\f[R]
|
|
.fi
|
|
.SS gitui
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: gitui [args...]
|
|
Launches gitui with the Catppuccin Frappe theme pre-applied.
|
|
\f[R]
|
|
.fi
|
|
.SS hist
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: hist
|
|
Searches shell history with fzf, inserts the selection into the command
|
|
line, and copies it to the clipboard via wl-copy.
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
* * * * *
|
|
.SS 5.5 Package Management
|
|
.SS pkg
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: pkg [-h] [-i|-u] <package> [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
|
|
\f[R]
|
|
.fi
|
|
.SS search
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: search [args...]
|
|
Interactive AUR package search and install via paru or yay.
|
|
Arch Linux only.
|
|
|
|
search neovim
|
|
\f[R]
|
|
.fi
|
|
.SS upgrade
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: upgrade
|
|
Full system upgrade via paru -Syu --noconfirm or yay -Syu --noconfirm.
|
|
Arch Linux only.
|
|
\f[R]
|
|
.fi
|
|
.SS cleanup
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: cleanup
|
|
Lists and removes orphan packages via pacman, logging their names to
|
|
\[ti]/.removed_orphans. Arch Linux only.
|
|
\f[R]
|
|
.fi
|
|
.SS parur
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
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
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
* * * * *
|
|
.SS 5.6 Dependency Management
|
|
.SS fish-deps
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
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 \[em] 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,
|
|
python3
|
|
|
|
fish-deps
|
|
fish-deps install
|
|
fish-deps update
|
|
fish-deps sync
|
|
\f[R]
|
|
.fi
|
|
.SS check_fish_deps
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: check_fish_deps
|
|
Backwards-compatibility alias for \[ga]fish-deps status\[ga].
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
* * * * *
|
|
.SS 5.7 System and Monitoring
|
|
.SS top
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: top [args...]
|
|
Launches btop as a modern resource monitor. Falls back to system top.
|
|
\f[R]
|
|
.fi
|
|
.SS swapstat
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: swapstat
|
|
Displays a colorized memory report: kernel swappiness, zRAM compression
|
|
ratio, zRAM device details, and active swap priorities.
|
|
\f[R]
|
|
.fi
|
|
.SS sbver
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
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
|
|
\f[R]
|
|
.fi
|
|
.SS ports
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: ports
|
|
Lists active TCP listeners with lsof, showing port/address without
|
|
hostname resolution.
|
|
\f[R]
|
|
.fi
|
|
.SS screensleep
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: screensleep
|
|
Turns off the display via KDE PowerDevil\[aq]s \[dq]Turn Off Screen\[dq] action,
|
|
invoked through busctl.
|
|
\f[R]
|
|
.fi
|
|
.SS lock
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: lock
|
|
Locks the current desktop session using loginctl lock-session.
|
|
\f[R]
|
|
.fi
|
|
.SS sudo-toggle
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
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.
|
|
\f[R]
|
|
.fi
|
|
.SS limine-edit
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
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.
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
* * * * *
|
|
.SS 5.8 Terminal Management
|
|
.SS tab
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: tab [args...]
|
|
Opens a new tab in Kitty (kitty \[at] launch --type=tab), WezTerm
|
|
(wezterm cli spawn), or Konsole. Uses current working directory,
|
|
or $cdto if set.
|
|
|
|
tab
|
|
\f[R]
|
|
.fi
|
|
.SS split
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
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
|
|
\f[R]
|
|
.fi
|
|
.SS spwin
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: spwin [args...]
|
|
Spawns a new terminal OS window in Kitty (via spawn-window.sh or
|
|
kitty \[at] launch --type=os-window) or WezTerm (wezterm cli spawn --new-window).
|
|
\f[R]
|
|
.fi
|
|
.SS detach
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: detach [-h] [--version] <command> [args...]
|
|
Runs a command fully detached via nohup with stdout/stderr discarded.
|
|
The command survives the current session.
|
|
|
|
detach rsync -a ./data remote:/backup/
|
|
\f[R]
|
|
.fi
|
|
.SS bkg
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: bkg <command> [args...]
|
|
Launches a command in the background via nohup with output discarded.
|
|
Simpler than detach; no version flag.
|
|
|
|
bkg firefox
|
|
\f[R]
|
|
.fi
|
|
.SS ssh
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
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\[at]host
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
* * * * *
|
|
.SS 5.9 Clipboard
|
|
.SS y
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: y [text...]
|
|
Copies text to the clipboard via wl-copy (Wayland) or xclip (X11).
|
|
Reads from stdin if no arguments given.
|
|
|
|
y \[dq]hello world\[dq]
|
|
ls | y
|
|
cat file.txt | y
|
|
\f[R]
|
|
.fi
|
|
.SS p
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: p [args...]
|
|
Outputs clipboard contents to stdout.
|
|
|
|
p | grep foo
|
|
p > file.txt
|
|
\f[R]
|
|
.fi
|
|
.SS paste
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Alias for p. Identical behaviour.
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
* * * * *
|
|
.SS 5.10 Network
|
|
.SS gip
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: gip
|
|
Fetches and prints both the public IPv4 and IPv6 address via
|
|
icanhazip.com.
|
|
\f[R]
|
|
.fi
|
|
.SS gip4
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: gip4
|
|
Fetches and prints the public IPv4 address.
|
|
\f[R]
|
|
.fi
|
|
.SS gip6
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: gip6
|
|
Fetches and prints the public IPv6 address. Returns 1 if IPv6 is
|
|
unavailable.
|
|
\f[R]
|
|
.fi
|
|
.SS ping
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: ping [args...]
|
|
Wraps prettyping with --nolegend. Pass --legend to show the legend.
|
|
Falls back to system ping.
|
|
|
|
ping google.com
|
|
\f[R]
|
|
.fi
|
|
.SS qr
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: qr [text...]
|
|
Generates a UTF-8 QR code from text or stdin. Uses qrencode locally;
|
|
falls back to the qrenco.de API.
|
|
|
|
qr \[dq]https://example.com\[dq]
|
|
echo \[dq]https://example.com\[dq] | qr
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
* * * * *
|
|
.SS 5.11 Pager and Logging
|
|
.SS logs
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: logs [-c <category>]
|
|
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
|
|
\f[R]
|
|
.fi
|
|
.SS smart_exit
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
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
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
* * * * *
|
|
.SS 5.12 AI and Developer Tools
|
|
.SS antigravity
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: antigravity [args...]
|
|
Runs the agy CLI (Antigravity AI assistant) with noisy deprecation
|
|
warnings filtered from stderr.
|
|
|
|
antigravity chat
|
|
\f[R]
|
|
.fi
|
|
.SS antigravity-ide
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: antigravity-ide [args...]
|
|
Runs the antigravity-ide editor with warnings filtered.
|
|
\f[R]
|
|
.fi
|
|
.SS antigravity-resume
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
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.
|
|
\f[R]
|
|
.fi
|
|
.SS claude-resume
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
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.
|
|
\f[R]
|
|
.fi
|
|
.SS claude-docs
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: claude-docs
|
|
Invokes Claude Code to analyze recent repository changes and update
|
|
README.md, ensuring all documented features and examples are accurate.
|
|
\f[R]
|
|
.fi
|
|
.SS claude-pr
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
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.
|
|
\f[R]
|
|
.fi
|
|
.SS code-resume
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: code-resume
|
|
Resumes the most recent AI session (Claude or Antigravity), preferring
|
|
the newest session file found in the current directory.
|
|
\f[R]
|
|
.fi
|
|
.SS superpowers
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
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
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
* * * * *
|
|
.SS 5.13 Media and Utilities
|
|
.SS dng2avif
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: dng2avif [-i <file>] [-o <file>] [-q <n>] [-s <n>] [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
|
|
\f[R]
|
|
.fi
|
|
.SS steam-dl
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: steam-dl
|
|
Launches Steam under systemd-inhibit, preventing the system from going
|
|
idle or sleeping while a download is in progress.
|
|
\f[R]
|
|
.fi
|
|
.SS spark
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: spark [--min=<n>] [--max=<n>] [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 \[dq]3 7 2 9 1\[dq] | spark
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
* * * * *
|
|
.SS 5.14 Miscellaneous
|
|
.SS config-help
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: config-help [SECTION]
|
|
config-help [SECTION] --html
|
|
config-help [SECTION] --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.
|
|
If SECTION is given, opens at the matching anchor.
|
|
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.
|
|
If SECTION is given, jumps to the nearest match.
|
|
--help / -h Print usage and navigation key reference.
|
|
|
|
config-help keybindings
|
|
config-help pkg
|
|
config-help --html
|
|
config-help pkg --html
|
|
config-help --man
|
|
config-help pkg --man
|
|
|
|
Also available as: help config [SECTION] [FLAGS]
|
|
\f[R]
|
|
.fi
|
|
.SS config-update
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: config-update [-h] [-n] [-f]
|
|
|
|
Pulls the latest fish configuration from the upstream repository
|
|
(https://git.rootiest.dev/rootiest/fish-config.git) into \[ti]/.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 \[ga]exec fish\[ga] 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
|
|
\f[R]
|
|
.fi
|
|
.SS config-toggle
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: config-toggle [-h]
|
|
|
|
Opens an interactive full-screen TUI for toggling the six opinionated
|
|
component categories (C1\[en]C6) and the master disable variable without
|
|
having to type or remember variable names. Two scope tabs allow
|
|
independent per-scope configuration:
|
|
|
|
Universal \[em] persists across all sessions (set -U)
|
|
Session \[em] current shell only (set -g)
|
|
|
|
Changes apply immediately on each value keypress. Always available
|
|
regardless of the __fish_config_opinionated master state.
|
|
|
|
Navigation:
|
|
↑ ↓ / k j Move cursor
|
|
← → / h l Set value: OFF ← DEFAULT → ON (clamped)
|
|
Tab Switch scope (Universal ↔ Session)
|
|
q / Escape Exit
|
|
|
|
Left/Right (or vim-style h/l) move the highlighted value one step along
|
|
the OFF\[en]DEFAULT\[en]ON scale and stop at the ends. DEFAULT erases the
|
|
variable so the master switch / built-in default applies.
|
|
|
|
Flags:
|
|
--help / -h Show usage.
|
|
|
|
config-toggle
|
|
\f[R]
|
|
.fi
|
|
.SS bash
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: bash [args...]
|
|
Switches to bash, with XDG config applied. On exit, $SHELL is reset
|
|
back to fish.
|
|
\f[R]
|
|
.fi
|
|
.SS bd-pull
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: bd-pull <owner/repo>
|
|
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
|
|
\f[R]
|
|
.fi
|
|
.SS cheat
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: cheat <topic> [args...]
|
|
Displays a colorized cheatsheet using cheat -c, falls back to tldr,
|
|
then man.
|
|
|
|
cheat tar
|
|
cheat git
|
|
\f[R]
|
|
.fi
|
|
.SS cffetch / ffetch
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: cffetch [args...] / ffetch [args...]
|
|
Clears the screen and displays system information via fastfetch with
|
|
the custom config at \[ti]/.fastfetch.jsonc. Falls back to neofetch.
|
|
\f[R]
|
|
.fi
|
|
.SS dockup
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: dockup [-h] [directory]
|
|
Pulls latest Docker images, restarts services in the given Docker
|
|
Compose project, and prunes dangling images.
|
|
|
|
dockup \[ti]/myapp
|
|
\f[R]
|
|
.fi
|
|
.SS joplin
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: joplin [args...]
|
|
Runs the Joplin CLI with Node.js deprecation warnings suppressed.
|
|
|
|
joplin ls
|
|
\f[R]
|
|
.fi
|
|
.SS ld
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: ld
|
|
Launches lazydocker targeting the currently active Docker context,
|
|
detected via docker context inspect.
|
|
\f[R]
|
|
.fi
|
|
.SS replay
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: replay <commands>
|
|
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 \[dq]source \[ti]/.bashrc\[dq]
|
|
replay \[dq]export FOO=bar\[dq]
|
|
\f[R]
|
|
.fi
|
|
.SS tmux-clean
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: tmux-clean
|
|
Kills all detached (unattached) tmux sessions, leaving attached ones
|
|
running.
|
|
\f[R]
|
|
.fi
|
|
.SS wake-lock
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: wake-lock <command> [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/
|
|
\f[R]
|
|
.fi
|
|
.SS zellij
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Synopsis: zellij [args...]
|
|
Launches zellij with the Catppuccin Mocha theme applied.
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
* * * * *
|
|
.SH 6. DEPENDENCY CATALOG
|
|
.PP
|
|
fish-deps manages these tools.
|
|
Run \f[V]fish-deps\f[R] to check status, or \f[V]fish-deps install\f[R]
|
|
to install missing ones.
|
|
.SS Required
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
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)
|
|
\f[R]
|
|
.fi
|
|
.SS Integrations
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
wakatime Developer time tracking
|
|
tailscale Mesh VPN client
|
|
\f[R]
|
|
.fi
|
|
.SS Recommended
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
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)
|
|
python3 Standalone interpreter \[em] used by the AI session helpers
|
|
(save_claude_session / save_antigravity_session) and the
|
|
paru/yay log cleaner. Note: uv does not provide python3 on
|
|
PATH, and Arch\[aq]s base does not include it, so it is listed
|
|
separately. All consumers degrade gracefully without it.
|
|
\f[R]
|
|
.fi
|
|
.SS Install Methods
|
|
.PP
|
|
The install priority for each tool:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
cargo Rust tools (eza, lsd, bat, dust, ov, ripgrep, trashy, zoxide,
|
|
starship) \[em] always gets the latest crate version
|
|
system PM paru / apt / brew / dnf / etc. \[em] for tools without a crate
|
|
git clone fzf \[em] installed from GitHub to \[ti]/.fzf/
|
|
curl starship installer, fisher bootstrap, uv installer
|
|
pipx Python-based tools
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
* * * * *
|
|
.SH 7. CUSTOMIZATION
|
|
.SS Machine-local Configuration
|
|
.PP
|
|
Place machine-specific settings that should not be committed to git in:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
\[ti]/.config/.user-dots/fish/local.fish
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
Typical uses: additional PATH entries, local aliases, hostname-specific
|
|
env vars, work-specific tool configs.
|
|
.SS Secrets and API Keys
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
\[ti]/.config/.user-dots/fish/secrets.fish
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
Store API tokens, GPG keys, private credentials here.
|
|
This file is never committed.
|
|
.PP
|
|
Both files are sourced at the end of config.fish on every interactive
|
|
session, so they can override anything set earlier.
|
|
.SS Overriding Configuration Variables
|
|
.PP
|
|
Any variable set in local.fish after the main config loads takes effect.
|
|
Example: to increase the scrollback history limit:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
# in local.fish
|
|
set -gx SCROLLBACK_HISTORY_MAX_FILES 200
|
|
\f[R]
|
|
.fi
|
|
.SS Fish Universal Variables
|
|
.PP
|
|
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 Opinionated Components (Minimal Mode)
|
|
.PP
|
|
Every opinionated piece of this config is active by default but can be
|
|
switched off through six category opt-out variables, each evaluated via
|
|
__fish_variable_check.
|
|
Set a variable to any falsy value (0, false, no, off, n) to disable its
|
|
category; erase it or set a truthy value (1, true, yes, on, y) to
|
|
re-enable.
|
|
Unset means enabled.
|
|
.PP
|
|
An explicit per-category truthy value takes precedence over the master
|
|
switch: setting __fish_config_opinionated=0 disables all unset
|
|
categories, but a category with an explicit truthy value remains enabled
|
|
regardless.
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Variable Disables
|
|
------------------------------ ------------------------------------
|
|
__fish_config_op_aliases Command shadows and flag injection:
|
|
ls->eza, cat->bat, cd->zoxide,
|
|
rm->trash, less->ov, top->btop,
|
|
ping->prettyping, ssh->kitten,
|
|
du->duf/dust, mkdir/bash wrappers,
|
|
history timestamps, grep/cp/mv/wget
|
|
flag injection, help intercept
|
|
__fish_config_op_autoexec Startup side-effects: Fisher
|
|
bootstrap, theme apply, paru/yay
|
|
wrapper generation, auto venv
|
|
activation, WakaTime hook
|
|
__fish_config_op_overrides Key and env overrides: Vi mode,
|
|
exit->smart_exit, PAGER/MANPAGER,
|
|
CDPATH, bang-bang system, autopair,
|
|
puffer, starship prompt, theme
|
|
colors, FZF_DEFAULT_OPTS, right
|
|
prompt
|
|
__fish_config_op_integrations Terminal/tool coupling: Kitty/
|
|
WezTerm window abbreviations, done
|
|
notifications, spwin/tab/split,
|
|
hist, logs, upgrade, WakaTime
|
|
__fish_config_op_logging Logging & capture: scrollback
|
|
capture on exit, paru/yay AUR log
|
|
wrappers, Kitty watcher capture;
|
|
sentinel file coordinates
|
|
cross-process state
|
|
__fish_config_op_greeting Greeting & first-run UI: per-session
|
|
fish_greeting override (defines empty
|
|
function late in config.fish to
|
|
suppress distro greetings such as
|
|
CachyOS fastfetch); first-run welcome
|
|
banner in conf.d/first_run.fish
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
Examples:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
# Disable command shadows only (rm becomes plain rm again):
|
|
set -U __fish_config_op_aliases off
|
|
|
|
# Full minimal mode \[em] disable all six categories at once:
|
|
set -U __fish_config_opinionated 0
|
|
|
|
# Re-enable everything:
|
|
set -Ue __fish_config_opinionated
|
|
|
|
# Minimal mode but keep the greeting:
|
|
set -U __fish_config_opinionated 0
|
|
set -U __fish_config_op_greeting 1
|
|
# (erase both to go back to full-flavor defaults)
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
Notes:
|
|
.IP \[bu] 2
|
|
Command shadows (rm, cat, ls, \&...)
|
|
react immediately; conf.d-level components (bindings, prompt,
|
|
abbreviations, hooks) take effect in new shells.
|
|
.IP \[bu] 2
|
|
With aliases disabled, rm falls back to bare \f[V]command rm\f[R] \[em]
|
|
files are deleted permanently, not trashed.
|
|
.IP \[bu] 2
|
|
Disabled integration commands (spwin, tab, split, hist, logs, upgrade)
|
|
print an error naming the variable that disabled them.
|
|
.IP \[bu] 2
|
|
On CachyOS, the distro fish config\[cq]s own aliases, history override,
|
|
and bang-bang bindings are stripped per category as well.
|
|
.SS Component Reference
|
|
.PP
|
|
The following tables detail every component in each category.
|
|
Use this reference to understand exactly which behaviors change when you
|
|
toggle a category variable.
|
|
.SS C1 \[em] Command Shadows
|
|
.PP
|
|
Disabling __fish_config_op_aliases restores standard system behavior for
|
|
all of these commands.
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Command / Alias Active behavior Disabled fallback
|
|
───────────────────────────────────────────────────────────────────────────
|
|
ls eza -l -a --icons --hyperlink system ls
|
|
cat bat syntax-highlighted; dirs → ls /usr/bin/cat
|
|
cd zoxide frecency-based navigation fish builtin cd
|
|
rm moves files to trash (recoverable) command rm (permanent)
|
|
less $PAGER → ov → less → more → cat system less
|
|
du duf (disk overview) or dust (dir tree) system du
|
|
top btop resource monitor system top
|
|
ping prettyping --nolegend animation system ping
|
|
ssh kitten ssh in Kitty terminal system ssh
|
|
rg rg --hyperlink-format=kitty system rg
|
|
mkdir verbose path-tree display on creation mkdir -p silently
|
|
bash XDG bashrc + $SHELL reset on exit system bash
|
|
history timestamps prepended to every entry fish builtin history
|
|
cp / mv forced -i confirmation prompt cp / mv unmodified
|
|
wget forced --continue (resume downloads) system wget
|
|
grep/fgrep/egrep forced --color=auto system grep variants
|
|
dir / vdir forced --color=auto system dir / vdir
|
|
help config intercepts \[dq]help config\[dq] → config-help fish builtin help
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
When C1 is disabled, \f[V]rm\f[R] uses bare \f[V]command rm\f[R] with no
|
|
wrapper \[em] files are permanently deleted, not trashed.
|
|
There is no intermediate safety net.
|
|
.SS C2 \[em] Startup Side-Effects
|
|
.PP
|
|
These run automatically without any user action.
|
|
Disabling __fish_config_op_autoexec prevents all of them.
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Component Trigger What it does
|
|
───────────────────────────────────────────────────────────────────────────
|
|
Fisher bootstrap First shell only Downloads and installs fisher
|
|
Fisher update After bootstrap Installs all fish_plugins entries
|
|
Catppuccin Mocha theme First shell only Applies theme via fish_config
|
|
paru wrapper Every startup Writes \[ti]/.local/bin/paru wrapper
|
|
yay wrapper Every startup Writes \[ti]/.local/bin/yay wrapper
|
|
Python venv activation On every cd Sources .venv/bin/activate.fish
|
|
WakaTime command hook On every command Reports to WakaTime API
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
When C2 is disabled: no Fisher install, no theme application, no
|
|
paru/yay wrapper generation, no automatic venv activation, and no
|
|
WakaTime reporting.
|
|
The first-run completion marker (__fish_config_first_run_complete) is
|
|
still set so the init does not re-run on subsequent shells.
|
|
.PP
|
|
Python venv activation fires on every directory change.
|
|
If a directory uses direnv (.envrc present), direnv takes priority and
|
|
auto-venv is skipped for that directory.
|
|
.SS C3 \[em] Key and Environment Overrides
|
|
.PP
|
|
These change fundamental shell behavior: how keys work, which pager
|
|
opens, and what the prompt looks like.
|
|
Disabling __fish_config_op_overrides removes all of them.
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Override What it replaces or sets
|
|
───────────────────────────────────────────────────────────────────────────
|
|
Vi mode fish_vi_key_bindings replaces default Emacs mode
|
|
exit → smart_exit exit wrapper that captures scrollback before closing
|
|
PAGER=ov ov used by git, man, and all $PAGER-aware tools
|
|
MANPAGER=bat pipeline man pages rendered with syntax highlighting
|
|
CDPATH=. \[ti]/projects \[ti] bare dir names resolve against \[ti]/projects and \[ti]
|
|
Bang-bang system ! and $ keys expand history; !\[ha], !*, !-N, !?str?,
|
|
\[ha]old\[ha]new abbreviations; six expand_bang_* helpers
|
|
Autopair ( [ { \[dq] \[aq] auto-close to (), [], {}, \[dq]\[dq], \[aq]\[aq]
|
|
Puffer key intercepts . ! $ * keys intercepted for smart expansion
|
|
Starship prompt fish_prompt replaced by Starship + OSC 133 markers
|
|
Catppuccin colors 30+ fish_color_* variables set to Mocha palette
|
|
FZF_DEFAULT_OPTS FZF themed to Catppuccin Mocha colors
|
|
Right prompt fish_right_prompt: Docker context + timestamp
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
The bang-bang system spans key_bindings.fish, abbr.fish, puffer.fish,
|
|
and six expand_bang_*.fish functions.
|
|
All are gated together \[em] disabling C3 removes the entire
|
|
bang-expansion system at once.
|
|
.PP
|
|
When C3 is disabled, \f[V]exit\f[R] falls back to \f[V]builtin exit\f[R]
|
|
with no scrollback capture, no Kitty IPC, and no file I/O on exit.
|
|
The scrollback capture block is independently controlled by C5 (see
|
|
below).
|
|
.SS C4 \[em] Terminal and Tool Integration
|
|
.PP
|
|
These features couple the shell to specific external tools.
|
|
Disabling __fish_config_op_integrations disables all of them.
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Component Requires
|
|
───────────────────────────────────────────────────────────────────────────
|
|
\[ti]60 Kitty/WezTerm abbrs Active Kitty or WezTerm session
|
|
(:w, :wv, :wh, :t, etc.)
|
|
Done desktop notifications Graphical desktop with a notification daemon
|
|
spwin Kitty or WezTerm
|
|
tab Kitty, WezTerm, or Konsole
|
|
split Kitty or WezTerm
|
|
hist fzf + wl-copy (Wayland clipboard)
|
|
logs fzf + ov; reads from \[ti]/.terminal_history/
|
|
upgrade paru or yay (Arch Linux only)
|
|
WakaTime hook wakatime CLI and a configured API key
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
Disabled integration commands (spwin, tab, split, hist, logs, upgrade)
|
|
print a colored error to stderr naming the variable that disabled them
|
|
rather than silently failing.
|
|
.SS C5 \[em] Logging and Capture
|
|
.PP
|
|
Three components capture shell output to disk.
|
|
Disabling __fish_config_op_logging skips all capture and removes the
|
|
logging wrappers.
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Component What it captures
|
|
───────────────────────────────────────────────────────────────────────────
|
|
Scrollback capture Terminal session output saved to:
|
|
\[ti]/.terminal_history/scrollback_YYYY-MM-DD_HH-MM-SS.log
|
|
paru wrapper All paru/AUR output captured to:
|
|
\[ti]/.terminal_history/paru_YYYY-MM-DD_HH-MM-SS.log
|
|
yay wrapper All yay/AUR output captured to:
|
|
\[ti]/.terminal_history/yay_YYYY-MM-DD_HH-MM-SS.log
|
|
Kitty watcher watcher.py captures scrollback when Kitty closes
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
Logging coordination via sentinel file
|
|
.PP
|
|
C5 uses a sentinel file to synchronize state between the shell and
|
|
out-of-process components (the Kitty watcher and all running shells):
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
\[ti]/.config/fish/.logging_disabled
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
Disabling __fish_config_op_logging: 1.
|
|
Creates the sentinel immediately in every open shell.
|
|
2.
|
|
Removes \[ti]/.local/bin/paru and \[ti]/.local/bin/yay logging wrappers;
|
|
bare /usr/bin/paru and /usr/bin/yay are used instead.
|
|
3.
|
|
Kitty\[cq]s watcher.py reads the sentinel on each save attempt and skips
|
|
capture \[em] no Kitty restart required.
|
|
4.
|
|
smart_exit stops saving scrollback logs.
|
|
.PP
|
|
Re-enabling __fish_config_op_logging: 1.
|
|
Removes the sentinel in every open shell.
|
|
2.
|
|
Regenerates paru/yay logging wrappers in \[ti]/.local/bin/.
|
|
3.
|
|
Kitty watcher resumes capture on the next session exit.
|
|
.PP
|
|
Changes propagate to all running shells through an event handler that
|
|
fires whenever __fish_config_op_logging changes \[em] no shell restart
|
|
needed.
|
|
.PP
|
|
Note: C3 and C5 compose independently.
|
|
C3 controls whether the smart_exit wrapper is active at all; C5 controls
|
|
only the scrollback-capture block inside it.
|
|
With C3 disabled, exit is plain builtin exit regardless of C5.
|
|
.SS C6 \[em] Greeting and First-Run UI
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Component What it shows
|
|
───────────────────────────────────────────────────────────────────────────
|
|
First-run welcome banner One-time message on first interactive session
|
|
fish_greeting override Empty function defined late in config.fish to
|
|
suppress distro greetings (e.g. CachyOS sets
|
|
fish_greeting to fastfetch by default)
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
When C6 is disabled, no greeting is printed by this config.
|
|
Any greeting set by the distro or other configs runs normally \[em] this
|
|
config simply does not override it.
|
|
.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 Mocha theme ships with this config in themes/ and is
|
|
applied on first run via \f[V]conf.d/first_run.fish\f[R].
|
|
Colors are stored in fish_variables (universal).
|
|
To switch variants, install a different theme from themes/:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
fish_config theme save \[dq]Catppuccin Latte\[dq]
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
* * * * *
|
|
.SH 8. FISHER PLUGINS
|
|
.PP
|
|
Fisher is bootstrapped automatically on the \f[B]first interactive
|
|
session\f[R] via \f[V]conf.d/first_run.fish\f[R].
|
|
This also applies the Catppuccin Mocha theme and prints a one-time
|
|
welcome message (gated by __fish_config_op_greeting; set it to 0 to
|
|
suppress).
|
|
Subsequent sessions skip all first-run logic with zero overhead.
|
|
.PP
|
|
To re-trigger first-run initialization (e.g., after a fresh install or
|
|
for testing), run:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
set -Ue __fish_config_first_run_complete
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
Then open a new shell.
|
|
.SS Fisher-Managed Plugins
|
|
.PP
|
|
The following plugins are fully managed by Fisher.
|
|
Their files are installed into the repo directory by Fisher and are
|
|
listed in \f[V].gitignore\f[R] \[em] do not commit them.
|
|
Fisher installs and updates them automatically.
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
jorgebucaran/fisher Plugin manager itself
|
|
meaningful-ooo/sponge Remove failed commands from history
|
|
\f[R]
|
|
.fi
|
|
.SS Sponge History Filtering
|
|
.PP
|
|
Sponge removes failed commands from history and, via
|
|
conf.d/sponge_privacy.fish, also filters privacy-sensitive commands
|
|
through three layers:
|
|
.PP
|
|
Layer 1 \[em] Static patterns (universal, persistent across sessions):
|
|
Commands matching any of these structural signatures are never recorded:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
--password / --token / --passphrase / --api-key flags with values
|
|
Inline env assignments: GITHUB_TOKEN=xxx, MY_API_KEY=abc
|
|
Fish set with sensitive names: set -gx GITHUB_TOKEN xxx
|
|
URLs with embedded credentials: https://user:pass\[at]host
|
|
HTTP Authorization headers: curl -H \[dq]Authorization: ...\[dq]
|
|
Basic auth flags: curl -u user:pass
|
|
sshpass, docker login -p, openssl -passin/-passout
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
Layer 2 \[em] Dynamic secret values (session globals, refreshed each
|
|
login): On the first prompt, after secrets.fish has loaded, the literal
|
|
values of all exported variables whose names suggest credentials (TOKEN,
|
|
PASSWORD, SECRET, API_KEY, etc.)
|
|
are collected, regex-escaped, and added as a session-scoped overlay.
|
|
Because globals shadow universals in Fish, the combined list is what
|
|
sponge sees.
|
|
Rotating a token takes effect on the next login automatically.
|
|
.PP
|
|
Layer 3 \[em] Per-command filter (sponge_filter_secrets): Catches
|
|
credentials in variables exported after login, such as tokens sourced
|
|
from a project .env file mid-session.
|
|
.PP
|
|
To add your own persistent patterns:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
set -U -a sponge_regex_patterns \[aq]your-regex-here\[aq]
|
|
\f[R]
|
|
.fi
|
|
.SS Bundled Plugin Functionality
|
|
.PP
|
|
The remaining plugin functionality is bundled directly with this config
|
|
rather than managed through Fisher.
|
|
The bundled versions include customizations for Fish 4.x compatibility
|
|
and improved behavior that differ from their upstream releases.
|
|
Installing them through Fisher would overwrite these customizations.
|
|
.PP
|
|
Bundled components and their upstream origins:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
catppuccin/fish → themes/ + conf.d/theme.fish
|
|
PatrickF1/fzf.fish → functions/_fzf_*.fish + conf.d/fzf.fish
|
|
franciscolourenco/done → conf.d/done.fish
|
|
jorgebucaran/autopair.fish → functions/_autopair_*.fish + conf.d/autopair.fish
|
|
nickeb96/puffer-fish → functions/_puffer_fish_*.fish + conf.d/puffer.fish
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
Do not run \f[V]fisher install\f[R] for these \[em] it will overwrite
|
|
the customized versions.
|
|
To update their behavior, edit the relevant bundled files directly.
|
|
.SS fish_plugins Manifest
|
|
.PP
|
|
The \f[V]fish_plugins\f[R] file at the config root:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
jorgebucaran/fisher Plugin manager itself
|
|
meaningful-ooo/sponge Remove failed commands from history
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
To update all Fisher-managed plugins, run \f[V]fisher update\f[R] or
|
|
\f[V]fish-deps update\f[R] which calls it as its first step.
|
|
.PP
|
|
* * * * *
|
|
.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 installs automatically on first launch and the Catppuccin Mocha
|
|
theme is applied.
|
|
All other plugin functionality is bundled directly with this config and
|
|
requires no additional installation.
|
|
.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
|
|
\f[C]
|
|
help config
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
ov renders the Markdown with syntax highlighting and section-based
|
|
navigation.
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
Space next section
|
|
\[ha] 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 \[aq]section\[aq])
|
|
q quit
|
|
\f[R]
|
|
.fi
|
|
.SS With bat
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
bat --language=markdown --paging=always \[ti]/.config/fish/docs/fish-config.md
|
|
\f[R]
|
|
.fi
|
|
.SS As a man page
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
help config --man
|
|
help config pkg --man
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
Opens the compiled docs/fish-config.1 directly via man -l, bypassing the
|
|
pager fallback chain.
|
|
If a section keyword is given, the pager opens at the nearest matching
|
|
heading.
|
|
The symlink and MANPATH are also configured automatically on shell start
|
|
for the standard invocation:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
man fish-config
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
NOTE: fish-config (hyphen) is this config\[cq]s man page.
|
|
fish_config (underscore) is fish\[cq]s built-in browser-based
|
|
configuration tool \[em] a completely separate command.
|
|
Do not mix them up.
|
|
.SS In the browser (HTML)
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
help config --html
|
|
help config pkg --html
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
Opens docs/html/index.html in the default web browser.
|
|
If a section keyword is given, the browser opens directly at the
|
|
matching anchor (resolved via docs/html/sitemap.json).
|
|
Browser detection queries the system\[cq]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.
|
|
.SS As a wiki
|
|
.PP
|
|
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.
|
|
.PP
|
|
The wiki is auto-generated from this file by the CI pipeline on every
|
|
push to main that changes docs/fish-config.md.
|
|
.SS Jumping to a section
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
help config keybindings
|
|
help config abbreviations
|
|
help config pkg
|
|
help config logs
|
|
help config fish-deps
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
The keyword is matched case-insensitively against section headings.
|
|
.SH AUTHORS
|
|
Rootiest.
|