docs: slim README to overview+docs pointer; expand offline manual
- README now contains only Overview, Documentation, Installation, Personalization, Attribution, and License; all detailed reference content has been removed since it is covered in the wiki - Add Documentation section above Installation pointing to docs/wiki/ - docs/fish-config.md: add §4.11 Shell Aliases (navigation dots, color overrides, safety wrappers, archives, system logs) - docs/fish-config.md: add Prompt and Theme subsection to §7 with Starship OSC 133 marker detail and FZF Catppuccin color values - Regenerate docs/wiki/ with all new content
This commit is contained in:
+173
-11
@@ -40,13 +40,31 @@ A production-grade Fish shell configuration targeting Fish 4.x. It provides:
|
||||
|
||||
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
|
||||
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 ~/.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 ~/.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)
|
||||
|
||||
---
|
||||
|
||||
@@ -66,6 +84,7 @@ The configuration is split across:
|
||||
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
|
||||
@@ -134,6 +153,71 @@ automatically on exit. Use `logs` to browse them interactively.
|
||||
CLAUDE_CODE_NO_FLICKER 1 — suppress terminal flicker in Claude Code
|
||||
CDPATH . ~/projects ~
|
||||
|
||||
## Pager Hierarchy
|
||||
|
||||
$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:
|
||||
|
||||
$PAGER → ov → less → more → cat
|
||||
|
||||
When bat is installed, man pages are rendered with syntax highlighting:
|
||||
|
||||
MANROFFOPT -c
|
||||
MANPAGER sh -c 'col -bx | bat -l man -p'
|
||||
|
||||
## Integrations
|
||||
|
||||
### Zoxide
|
||||
|
||||
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.
|
||||
|
||||
### DirEnv
|
||||
|
||||
Automatically loads .envrc files on directory change. Takes priority over
|
||||
the auto-venv logic — if a directory is managed by direnv, the auto-venv
|
||||
activation is skipped entirely.
|
||||
|
||||
### Auto Python Venv
|
||||
|
||||
When entering a directory that contains a .venv/, the virtualenv is activated
|
||||
automatically and deactivated when you leave the project tree.
|
||||
|
||||
### WakaTime
|
||||
|
||||
Every shell command is reported to WakaTime for time-tracking. Set
|
||||
FISH_WAKATIME_DISABLED=1 to disable without removing the plugin.
|
||||
|
||||
### Tailscale
|
||||
|
||||
Full tab completion for the tailscale CLI is provided via conf.d/tailscale.fish.
|
||||
|
||||
### Done Notifications
|
||||
|
||||
Desktop notifications fire when a command takes longer than 10 seconds and
|
||||
the terminal window is not focused. Configured via fish universal variables:
|
||||
|
||||
__done_min_cmd_duration 10000 ms
|
||||
__done_notification_urgency_level low
|
||||
|
||||
### Scrollback History
|
||||
|
||||
When running inside Kitty, closing a shell session via exit saves a timestamped
|
||||
scrollback snapshot to SCROLLBACK_HISTORY_DIR. Files are named:
|
||||
|
||||
scrollback_YYYY-MM-DD_HH-MM-SS.log
|
||||
|
||||
The paru and yay wrappers (auto-generated in ~/.local/bin/) tee all output to:
|
||||
|
||||
paru_YYYY-MM-DD_HH-MM-SS.log
|
||||
yay_YYYY-MM-DD_HH-MM-SS.log
|
||||
|
||||
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 --no-log (or exit -n) to skip capture.
|
||||
|
||||
---
|
||||
|
||||
# 2. PATH SETUP
|
||||
@@ -193,11 +277,14 @@ are active in Insert, Normal, and Visual modes unless noted.
|
||||
line to open an fzf picker and insert a selection
|
||||
at the cursor position.
|
||||
|
||||
## FZF Bindings (from fzf --fish integration)
|
||||
## FZF Bindings (from PatrickF1/fzf.fish)
|
||||
|
||||
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
|
||||
|
||||
---
|
||||
|
||||
@@ -342,6 +429,48 @@ These are implemented as keybinding helpers, but can also be typed:
|
||||
bsh bd show
|
||||
lb lazybeads
|
||||
|
||||
## 4.11 Shell Aliases
|
||||
|
||||
These aliases are defined in conf.d/tricks.fish via alias (which creates Fish
|
||||
functions). They are active in all interactive sessions.
|
||||
|
||||
### Navigation
|
||||
|
||||
.. cd ..
|
||||
... cd ../..
|
||||
.... cd ../../..
|
||||
..... cd ../../../..
|
||||
...... cd ../../../../..
|
||||
|
||||
### Color Overrides
|
||||
|
||||
Force color output for common tools:
|
||||
|
||||
grep grep --color=auto
|
||||
fgrep fgrep --color=auto
|
||||
egrep egrep --color=auto
|
||||
dir dir --color=auto
|
||||
vdir vdir --color=auto
|
||||
|
||||
### Safety Wrappers
|
||||
|
||||
Add -i (interactive confirmation) to destructive commands:
|
||||
|
||||
cp cp -i
|
||||
mv mv -i
|
||||
|
||||
### Archives and Networking
|
||||
|
||||
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
|
||||
|
||||
### System Logs
|
||||
|
||||
jctl journalctl -p 3 -xb Show priority-3 (error) journal entries
|
||||
from the current boot
|
||||
|
||||
---
|
||||
|
||||
# 5. FUNCTIONS REFERENCE
|
||||
@@ -1237,6 +1366,39 @@ 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.
|
||||
|
||||
## Prompt and Theme
|
||||
|
||||
### Starship
|
||||
|
||||
The primary prompt is Starship, initialized by conf.d/starship.fish.
|
||||
Configure it via ~/.config/starship.toml.
|
||||
|
||||
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's
|
||||
built-in prompt handles these markers automatically.
|
||||
|
||||
### FZF
|
||||
|
||||
FZF is themed to Catppuccin Mocha via FZF_DEFAULT_OPTS set in
|
||||
integrations/fzf.fish. The colors applied:
|
||||
|
||||
Background: #1E1E2E (base) #313244 (surface0)
|
||||
Foreground: #CDD6F4 (text)
|
||||
Highlights: #F38BA8 (red) #CBA6F7 (mauve) #B4BEFE (lavender)
|
||||
|
||||
To customize, override FZF_DEFAULT_OPTS in local.fish.
|
||||
|
||||
### Catppuccin Mocha Syntax Highlighting
|
||||
|
||||
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:
|
||||
|
||||
fish_config theme save "Catppuccin Latte"
|
||||
|
||||
---
|
||||
|
||||
# 8. FISHER PLUGINS
|
||||
|
||||
@@ -48,4 +48,69 @@ automatically on exit. Use `logs` to browse them interactively.
|
||||
CLAUDE_CODE_NO_FLICKER 1 — suppress terminal flicker in Claude Code
|
||||
CDPATH . ~/projects ~
|
||||
|
||||
## Pager Hierarchy
|
||||
|
||||
$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:
|
||||
|
||||
$PAGER → ov → less → more → cat
|
||||
|
||||
When bat is installed, man pages are rendered with syntax highlighting:
|
||||
|
||||
MANROFFOPT -c
|
||||
MANPAGER sh -c 'col -bx | bat -l man -p'
|
||||
|
||||
## Integrations
|
||||
|
||||
### Zoxide
|
||||
|
||||
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.
|
||||
|
||||
### DirEnv
|
||||
|
||||
Automatically loads .envrc files on directory change. Takes priority over
|
||||
the auto-venv logic — if a directory is managed by direnv, the auto-venv
|
||||
activation is skipped entirely.
|
||||
|
||||
### Auto Python Venv
|
||||
|
||||
When entering a directory that contains a .venv/, the virtualenv is activated
|
||||
automatically and deactivated when you leave the project tree.
|
||||
|
||||
### WakaTime
|
||||
|
||||
Every shell command is reported to WakaTime for time-tracking. Set
|
||||
FISH_WAKATIME_DISABLED=1 to disable without removing the plugin.
|
||||
|
||||
### Tailscale
|
||||
|
||||
Full tab completion for the tailscale CLI is provided via conf.d/tailscale.fish.
|
||||
|
||||
### Done Notifications
|
||||
|
||||
Desktop notifications fire when a command takes longer than 10 seconds and
|
||||
the terminal window is not focused. Configured via fish universal variables:
|
||||
|
||||
__done_min_cmd_duration 10000 ms
|
||||
__done_notification_urgency_level low
|
||||
|
||||
### Scrollback History
|
||||
|
||||
When running inside Kitty, closing a shell session via exit saves a timestamped
|
||||
scrollback snapshot to SCROLLBACK_HISTORY_DIR. Files are named:
|
||||
|
||||
scrollback_YYYY-MM-DD_HH-MM-SS.log
|
||||
|
||||
The paru and yay wrappers (auto-generated in ~/.local/bin/) tee all output to:
|
||||
|
||||
paru_YYYY-MM-DD_HH-MM-SS.log
|
||||
yay_YYYY-MM-DD_HH-MM-SS.log
|
||||
|
||||
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 --no-log (or exit -n) to skip capture.
|
||||
|
||||
---
|
||||
|
||||
@@ -40,10 +40,13 @@ are active in Insert, Normal, and Visual modes unless noted.
|
||||
line to open an fzf picker and insert a selection
|
||||
at the cursor position.
|
||||
|
||||
## FZF Bindings (from fzf --fish integration)
|
||||
## FZF Bindings (from PatrickF1/fzf.fish)
|
||||
|
||||
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
|
||||
|
||||
---
|
||||
|
||||
@@ -143,4 +143,46 @@ These are implemented as keybinding helpers, but can also be typed:
|
||||
bsh bd show
|
||||
lb lazybeads
|
||||
|
||||
## 4.11 Shell Aliases
|
||||
|
||||
These aliases are defined in conf.d/tricks.fish via alias (which creates Fish
|
||||
functions). They are active in all interactive sessions.
|
||||
|
||||
### Navigation
|
||||
|
||||
.. cd ..
|
||||
... cd ../..
|
||||
.... cd ../../..
|
||||
..... cd ../../../..
|
||||
...... cd ../../../../..
|
||||
|
||||
### Color Overrides
|
||||
|
||||
Force color output for common tools:
|
||||
|
||||
grep grep --color=auto
|
||||
fgrep fgrep --color=auto
|
||||
egrep egrep --color=auto
|
||||
dir dir --color=auto
|
||||
vdir vdir --color=auto
|
||||
|
||||
### Safety Wrappers
|
||||
|
||||
Add -i (interactive confirmation) to destructive commands:
|
||||
|
||||
cp cp -i
|
||||
mv mv -i
|
||||
|
||||
### Archives and Networking
|
||||
|
||||
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
|
||||
|
||||
### System Logs
|
||||
|
||||
jctl journalctl -p 3 -xb Show priority-3 (error) journal entries
|
||||
from the current boot
|
||||
|
||||
---
|
||||
|
||||
@@ -37,4 +37,37 @@ 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.
|
||||
|
||||
## Prompt and Theme
|
||||
|
||||
### Starship
|
||||
|
||||
The primary prompt is Starship, initialized by conf.d/starship.fish.
|
||||
Configure it via ~/.config/starship.toml.
|
||||
|
||||
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's
|
||||
built-in prompt handles these markers automatically.
|
||||
|
||||
### FZF
|
||||
|
||||
FZF is themed to Catppuccin Mocha via FZF_DEFAULT_OPTS set in
|
||||
integrations/fzf.fish. The colors applied:
|
||||
|
||||
Background: #1E1E2E (base) #313244 (surface0)
|
||||
Foreground: #CDD6F4 (text)
|
||||
Highlights: #F38BA8 (red) #CBA6F7 (mauve) #B4BEFE (lavender)
|
||||
|
||||
To customize, override FZF_DEFAULT_OPTS in local.fish.
|
||||
|
||||
### Catppuccin Mocha Syntax Highlighting
|
||||
|
||||
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:
|
||||
|
||||
fish_config theme save "Catppuccin Latte"
|
||||
|
||||
---
|
||||
|
||||
+25
-7
@@ -13,13 +13,31 @@ A production-grade Fish shell configuration targeting Fish 4.x. It provides:
|
||||
|
||||
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
|
||||
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 ~/.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 ~/.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)
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user