docs(site): improve UI, add catppuccin theme, fix MDX bugs
This commit is contained in:
@@ -2,7 +2,7 @@
|
||||
title: C1 — Command Shadows
|
||||
---
|
||||
|
||||
Disabling __fish_config_op_aliases restores standard system behavior for
|
||||
Disabling `__fish_config_op_aliases` restores standard system behavior for
|
||||
all of these commands.
|
||||
|
||||
Command / Alias Active behavior Disabled fallback
|
||||
|
||||
@@ -3,7 +3,7 @@ title: C2 — Startup Side-Effects
|
||||
---
|
||||
|
||||
These run automatically without any user action. Disabling
|
||||
__fish_config_op_autoexec prevents all of them.
|
||||
`__fish_config_op_autoexec` prevents all of them.
|
||||
|
||||
Component Trigger What it does
|
||||
───────────────────────────────────────────────────────────────────────────
|
||||
@@ -23,15 +23,15 @@ 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
|
||||
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
|
||||
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
|
||||
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
|
||||
@@ -40,6 +40,6 @@ 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
|
||||
(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.
|
||||
|
||||
|
||||
@@ -3,7 +3,7 @@ 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
|
||||
and what the prompt looks like. Disabling `__fish_config_op_overrides` removes
|
||||
all of them.
|
||||
|
||||
Override What it replaces or sets
|
||||
@@ -25,8 +25,8 @@ all of them.
|
||||
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
|
||||
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
|
||||
|
||||
@@ -3,11 +3,11 @@ title: C4 — Terminal and Tool Integration
|
||||
---
|
||||
|
||||
These features couple the shell to specific external tools. Disabling
|
||||
__fish_config_op_integrations disables all of them.
|
||||
`__fish_config_op_integrations` disables all of them.
|
||||
|
||||
Component Requires
|
||||
───────────────────────────────────────────────────────────────────────────
|
||||
~60 Kitty/WezTerm abbrs Active Kitty or WezTerm session
|
||||
≈ 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
|
||||
@@ -18,7 +18,7 @@ __fish_config_op_integrations disables all of them.
|
||||
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
|
||||
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.
|
||||
|
||||
|
||||
@@ -3,10 +3,12 @@ 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
|
||||
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.
|
||||
|
||||
CAUTION: This configuration is capable of silently recording terminal output and secrets directly to disk. See below for details on how this capture mechanism works, where files are stored, and how to manage its state.
|
||||
|
||||
# Turn it on (persistently, in every shell):
|
||||
set -U __fish_config_op_logging on
|
||||
|
||||
@@ -16,38 +18,38 @@ it is off, all capture is skipped and the logging wrappers are removed.
|
||||
Component What it captures
|
||||
───────────────────────────────────────────────────────────────────────────
|
||||
Scrollback capture Terminal session output saved to:
|
||||
~/.terminal_history/scrollback_YYYY-MM-DD_HH-MM-SS.log
|
||||
`~/.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
|
||||
`~/.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
|
||||
`~/.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
|
||||
`~/.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
|
||||
`~/.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
|
||||
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.
|
||||
`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
|
||||
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
|
||||
`$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.
|
||||
|
||||
@@ -69,12 +71,12 @@ 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
|
||||
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
|
||||
windows only; runtime disable is still handled by the `.logging_disabled`
|
||||
sentinel.
|
||||
|
||||
Logging coordination via sentinel file
|
||||
@@ -85,26 +87,26 @@ 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
|
||||
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):
|
||||
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
|
||||
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.
|
||||
5. Stops `tmux pipe-pane` capture in every open fish shell inside tmux.
|
||||
|
||||
Enabling __fish_config_op_logging:
|
||||
Enabling `__fish_config_op_logging`:
|
||||
1. Removes the sentinel in every open shell.
|
||||
2. Regenerates paru/yay logging wrappers in ~/.local/bin/.
|
||||
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.
|
||||
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
|
||||
|
||||
Reference in New Issue
Block a user