docs: restructure customization and components reference into nested directories
This commit is contained in:
@@ -0,0 +1,33 @@
|
||||
---
|
||||
title: C1 — Command Shadows
|
||||
---
|
||||
|
||||
Disabling __fish_config_op_aliases restores standard system behavior for
|
||||
all of these commands.
|
||||
|
||||
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 "help config" → config-help fish builtin help
|
||||
claude auto-links AGENTS.md as CLAUDE.md before launch command claude
|
||||
edit multi-editor launcher (GUI/term + fallbacks) $EDITOR/nvim/nano/vi
|
||||
|
||||
When C1 is disabled, `rm` uses bare `command rm` with no wrapper — files
|
||||
are permanently deleted, not trashed. There is no intermediate safety net.
|
||||
|
||||
@@ -0,0 +1,45 @@
|
||||
---
|
||||
title: C2 — Startup Side-Effects
|
||||
---
|
||||
|
||||
These run automatically without any user action. Disabling
|
||||
__fish_config_op_autoexec prevents all of them.
|
||||
|
||||
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 ~/.local/bin/paru wrapper
|
||||
yay wrapper Every startup Writes ~/.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
|
||||
Auto-pull fast-forward On entering a repo Background ff-only git pull
|
||||
user-dots symlink Every startup Links $__fish_config_dir/user-dots
|
||||
to $__fish_user_dots_path
|
||||
|
||||
When C2 is disabled: no Fisher install, no theme application, no paru/yay
|
||||
wrapper generation, no automatic venv activation, no WakaTime reporting,
|
||||
no auto-pull (the PWD handler is never registered), and the user-dots
|
||||
convenience symlink is not created. The symlink is git-ignored and only ever
|
||||
managed as a symlink — a real file or directory at that path is left untouched.
|
||||
The symlink has its own opt-out independent of C2: set __fish_user_dots_symlink
|
||||
to a falsy value (or toggle "Dots link" off on the config-settings Paths page)
|
||||
to stop generating it and remove any existing link — honoured even when C2 is
|
||||
enabled. Managed by the __fish_user_dots_link helper.
|
||||
The first-run completion marker (__fish_config_first_run_complete) is still
|
||||
set so the init does not re-run on subsequent shells.
|
||||
|
||||
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.
|
||||
|
||||
Auto-pull fast-forwards opted-in repositories in the background when you cd
|
||||
into them. The fish-config repo is always covered; other repos are added with
|
||||
the `auto-pull` command (see its entry in the functions reference). It only
|
||||
ever fast-forwards a clean repo whose branch has an upstream — never rebases,
|
||||
merges, or overwrites work — so it is a no-op on dirty trees, divergent
|
||||
branches, or repos without a remote. The handler fires once per repo entry
|
||||
(not on every sub-directory cd). The registry is machine-local at
|
||||
`$__fish_user_dots_path/auto-pull.list` (defaults to `~/.config/.user-dots/fish/auto-pull.list`) and is never committed.
|
||||
|
||||
@@ -0,0 +1,35 @@
|
||||
---
|
||||
title: C3 — Key and Environment Overrides
|
||||
---
|
||||
|
||||
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.
|
||||
|
||||
Override What it replaces or sets
|
||||
───────────────────────────────────────────────────────────────────────────
|
||||
Vi mode fish_vi_key_bindings replaces default Emacs mode
|
||||
PATH setup Prepends custom bin directories to the PATH
|
||||
exit → smart_exit exit wrapper that captures scrollback before closing
|
||||
PAGER=ov ov used by git, man, and all $PAGER-aware tools
|
||||
EDITOR=nvim nvim fallback to vi for git commit, etc.
|
||||
GPG_TTY Sets GPG_TTY to current terminal tty
|
||||
MANPAGER=bat pipeline man pages rendered with syntax highlighting
|
||||
CDPATH=. ~/projects ~ bare dir names resolve against ~/projects and ~
|
||||
Bang-bang system ! and $ keys expand history; !^, !*, !-N, !?str?,
|
||||
^old^new abbreviations; six expand_bang_* helpers
|
||||
Autopair ( [ { " ' auto-close to (), [], {}, "", ''
|
||||
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: exit code (on failure) + dim timestamp; always rendered; Docker context added when starship+C3 active
|
||||
|
||||
The bang-bang system spans key_bindings.fish, abbr.fish, puffer.fish, and
|
||||
six expand_bang_*.fish functions. All are gated together — disabling C3
|
||||
removes the entire bang-expansion system at once.
|
||||
|
||||
When C3 is disabled, `exit` falls back to `builtin exit` 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).
|
||||
|
||||
@@ -0,0 +1,24 @@
|
||||
---
|
||||
title: C4 — Terminal and Tool Integration
|
||||
---
|
||||
|
||||
These features couple the shell to specific external tools. Disabling
|
||||
__fish_config_op_integrations disables all of them.
|
||||
|
||||
Component Requires
|
||||
───────────────────────────────────────────────────────────────────────────
|
||||
~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 ~/.terminal_history/
|
||||
upgrade paru or yay (Arch Linux only)
|
||||
WakaTime hook wakatime CLI and a configured API key
|
||||
|
||||
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.
|
||||
|
||||
@@ -0,0 +1,112 @@
|
||||
---
|
||||
title: C5 — Logging and Capture
|
||||
---
|
||||
|
||||
Five components capture shell output to disk. Unlike every other category,
|
||||
C5 is opt-in: it stays off until __fish_config_op_logging is set to an
|
||||
explicit truthy value, and a truthy master switch does not enable it. While
|
||||
it is off, all capture is skipped and the logging wrappers are removed.
|
||||
|
||||
# Turn it on (persistently, in every shell):
|
||||
set -U __fish_config_op_logging on
|
||||
|
||||
# Turn it back off:
|
||||
set -U __fish_config_op_logging off # or: set -Ue __fish_config_op_logging
|
||||
|
||||
Component What it captures
|
||||
───────────────────────────────────────────────────────────────────────────
|
||||
Scrollback capture Terminal session output saved to:
|
||||
~/.terminal_history/scrollback_YYYY-MM-DD_HH-MM-SS.log
|
||||
tmux pane capture Continuous pane stream via pipe-pane, saved to:
|
||||
~/.terminal_history/tmux_<session>-w<win>-p<pane>_YYYY-MM-DD_HH-MM-SS.log
|
||||
zellij pane capture Pane scrollback snapshot on shell exit, saved to:
|
||||
~/.terminal_history/zellij_<session>-p<pane>_YYYY-MM-DD_HH-MM-SS.log
|
||||
paru wrapper All paru/AUR output captured to:
|
||||
~/.terminal_history/paru_YYYY-MM-DD_HH-MM-SS.log
|
||||
yay wrapper All yay/AUR output captured to:
|
||||
~/.terminal_history/yay_YYYY-MM-DD_HH-MM-SS.log
|
||||
Kitty watcher watcher.py captures scrollback when Kitty closes
|
||||
|
||||
NOTE: **Turning off logging does not delete any existing logs.**
|
||||
They remain in `$SCROLLBACK_HISTORY_DIR` (defaults to: `~/.terminal_history/`)
|
||||
until you remove them manually.
|
||||
|
||||
The tmux capture starts automatically when fish launches inside any tmux
|
||||
pane ($TMUX is set). It uses tmux's native pipe-pane to stream all pane
|
||||
output directly to disk without an intermediate process. Each fish shell
|
||||
session gets its own log file; a new log is created on each shell start
|
||||
(including exec fish and new splits). Before each new log, the oldest
|
||||
tmux_*.log files are pruned (by modification time) to keep the total within
|
||||
SCROLLBACK_HISTORY_MAX_FILES, matching the paru/yay wrapper behaviour.
|
||||
|
||||
The zellij capture works differently: Zellij has no live output-streaming
|
||||
facility like pipe-pane, so the log is taken as a one-shot snapshot when the
|
||||
shell exits, via `zellij action dump-screen --full --ansi` (the --ansi flag
|
||||
preserves color). The dump is captured on the fish process's stdout and
|
||||
written to the log file by fish itself (not via `--path`, which would make the
|
||||
zellij server write the file). A fish_exit handler (registered whenever
|
||||
$ZELLIJ is set) writes the pane's full scrollback and then prunes old
|
||||
zellij_*.log files the same way. Because the capture happens at exit, toggling
|
||||
__fish_config_op_logging takes effect on the next exit with no restart or
|
||||
sentinel coordination needed — the C5 guard is re-checked when the handler
|
||||
fires.
|
||||
|
||||
LIMITATION — zellij capture only fires on a clean shell exit (typing `exit`,
|
||||
Ctrl-D, or a logout), because that is when the fish_exit handler runs. It does
|
||||
NOT capture when you close a pane or quit zellij through zellij itself:
|
||||
|
||||
- Closing a pane signals the shell and tears the pane down concurrently, so
|
||||
even if the handler runs, `dump-screen` may find the pane buffer already
|
||||
gone.
|
||||
- Quitting zellij kills the zellij server, and `dump-screen` needs a live
|
||||
server to read from — there is nothing left to snapshot.
|
||||
|
||||
This is a structural difference from tmux, NOT a bug. tmux streams pane output
|
||||
to disk continuously via pipe-pane, so whatever was printed is already saved
|
||||
no matter how the pane dies. Zellij can only snapshot, and the only reliable
|
||||
snapshot point from the shell is a clean exit. To guarantee a zellij pane is
|
||||
logged, end the session with `exit` or Ctrl-D rather than zellij's close-pane
|
||||
or quit actions.
|
||||
|
||||
The Kitty watcher is managed by the kitty-logging command: it symlinks the
|
||||
watcher (fish-config-watcher.py) into the Kitty config directory and wires it
|
||||
into kitty.conf via a managed block. Inside Kitty, a non-blocking
|
||||
per-session reminder points first-time users at `kitty-logging install` until
|
||||
they install or run `kitty-logging dismiss`; the reminder is itself gated on
|
||||
C5, so it stays silent until you enable logging. Install affects new Kitty
|
||||
windows only; runtime disable is still handled by the .logging_disabled
|
||||
sentinel.
|
||||
|
||||
Logging coordination via sentinel file
|
||||
|
||||
C5 uses a sentinel file to synchronize state between the shell and
|
||||
out-of-process components (the Kitty watcher and all running shells):
|
||||
|
||||
~/.config/fish/.logging_disabled
|
||||
|
||||
Because C5 is off by default, the sentinel is present on a fresh install —
|
||||
the startup sync in conf.d/logging-events.fish reconciles it on every shell
|
||||
start, so it appears without any action on your part.
|
||||
|
||||
Disabling __fish_config_op_logging (or leaving it unset):
|
||||
1. Creates the sentinel immediately in every open shell.
|
||||
2. Removes ~/.local/bin/paru and ~/.local/bin/yay logging wrappers;
|
||||
bare /usr/bin/paru and /usr/bin/yay are used instead.
|
||||
3. Kitty's watcher.py reads the sentinel on each save attempt and
|
||||
skips capture — no Kitty restart required.
|
||||
4. smart_exit stops saving scrollback logs.
|
||||
5. Stops tmux pipe-pane capture in every open fish shell inside tmux.
|
||||
|
||||
Enabling __fish_config_op_logging:
|
||||
1. Removes the sentinel in every open shell.
|
||||
2. Regenerates paru/yay logging wrappers in ~/.local/bin/.
|
||||
3. Kitty watcher resumes capture on the next session exit.
|
||||
4. Restarts tmux pipe-pane capture in every open fish shell inside tmux.
|
||||
|
||||
Changes propagate to all running shells through an event handler that fires
|
||||
whenever __fish_config_op_logging changes — no shell restart needed.
|
||||
|
||||
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.
|
||||
|
||||
@@ -0,0 +1,15 @@
|
||||
---
|
||||
title: C6 — Greeting and First-Run UI
|
||||
---
|
||||
|
||||
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)
|
||||
|
||||
When C6 is disabled, no greeting is printed by this config. Any greeting
|
||||
set by the distro or other configs runs normally — this config simply does
|
||||
not override it.
|
||||
|
||||
@@ -0,0 +1,12 @@
|
||||
---
|
||||
title: Components Reference
|
||||
manTitle: 8. COMPONENTS REFERENCE
|
||||
sidebar:
|
||||
order: 12
|
||||
helpKeywords:
|
||||
- componentsreference
|
||||
---
|
||||
The following tables detail every component in each category. Use this
|
||||
reference to understand exactly which behaviors change when you toggle a
|
||||
category variable.
|
||||
|
||||
Reference in New Issue
Block a user