Raw multi-line armored key piped through 'echo | gpg --import' came out
CRC-corrupted (Invalid keyring) on the first real run -- something in the
secret/env round-trip mangles embedded newlines. Regenerated the bot key
(old one is unrecoverable, secrets are write-only) and store it
base64-encoded, decoded with base64 -d before import.
agy uses different resume syntax than claude: -c/--continue always
resumes the most-recent session, while --conversation takes a
specific session id. Previously -r/--resume was blanket-mapped to
-c/--continue, breaking `agy --resume <id>` and `agy -r=<id>` style
invocations. Now bare -r/--resume (no id following) maps to
-c/--continue; -r/--resume given an id (via =id or a following
non-flag word) maps to --conversation(=id).
actions@gitea was never a verified email on any Gitea account, so the
CI docs-regen commit (git commit && git push, done client-side in the
runner) could never show as verified regardless of server-side
[repository.signing] config -- Gitea only signs commits it generates
itself (merge button, web editor, wiki), never ones a client pushes.
Import a dedicated passphrase-less key for a new fishconfig-bot
account (verified email, no login) from the CI_GPG_PRIVATE_KEY repo
secret and sign with it instead.
git branch -vv marks column 1 with '+' (not '*') for a branch checked
out in another linked worktree. Only '*' was stripped from $1, so a
gone branch shown with '+' left a bogus "+" entry in $gone_branches
that then failed to delete: error: branch '+' not found.
Add a regression case reproducing the '+'-marked gone-branch line via
the existing git-clean mock handler in tests/test-network-fish.fish.
mkcd's create-and-cd behavior plus git init, remote linking, and
optional remote creation via a user-configured command template
($MKREP_REMOTE_CMD, {name}/{user} placeholders).
The guard added in 208ad95 had no test. This is the failure worth
covering, because it is the one that does not announce itself: with an
empty dump every row renders as DEFAULT, indistinguishable from a config
where nothing is set, so the user toggles from a false baseline.
Reaching the guard needs a real terminal -- the isatty check sits in
front of it -- so the case runs fish under a pty via python3's stdlib
pty module, which this suite already depends on. An empty
__config_settings_state is shadowed in to fake the failure.
The pty reader's 15s deadline is load-bearing rather than defensive: if
the guard regresses, config-settings does not fail, it opens the TUI and
blocks on getch(), so an unbounded read would hang the suite instead of
failing it. Verified both ways -- passes with the guard, and with the
guard removed the deadline fires and the case fails with a legible
excerpt rather than a screenful of escape sequences.
An empty dump does not fail loudly: the TUI renders every row as
DEFAULT, which is indistinguishable from a config where nothing is set.
That is a wrong answer rather than a missing one -- the user would be
looking at ON rows reported as DEFAULT -- so the launcher now checks the
dump is non-empty and bails with a message instead. The taxonomy alone
guarantees output on any working checkout. Also guard a failed mktemp,
which would otherwise send the dump to /state and hand an empty path to
rm -rf.
README: mention that / searches sub-categories across every category.
test_concat_section_five_stays_verbatim forbids backticks inside
generated Section 5 entries -- function headers are rendered verbatim, so
inline code markup there breaks the man page.
config-settings is now a launcher for scripts/config-settings-tui.py,
drawn with Python's stdlib curses. The seven fish files that hand-rolled
the ANSI renderer are gone, along with the golden harness that had to pin
their byte-exact output.
The TUI is a child process, so it can neither read the session's global
variables nor write them. State goes in as a dump from the new
__config_settings_state; the edits come back as a fish script that
config-settings sources, which is what lets the Session page's `set -g`
land in the caller's shell instead of in a child that is about to exit.
Every edit is emitted as a call to __config_settings_apply or
__config_settings_set_value, so list splitting, the SCROLLBACK_HISTORY_*
export mirror and the shadow-warning suppression all stay in the fish
layer that already owned them.
The consequence, and the one behaviour change: edits are applied in one
batch on exit rather than on each keypress. The status bar shows a
pending count.
New: `/` filters the current page, and on the Universal and Session pages
it reaches into every category's sub-categories, listing hits as
"Category › Sub" so a sub-category can be toggled without drilling into
its parent first. Also a `?` help overlay, mouse selection, and a
drill-down page that leads with the category's own toggle.
Gone with the renderer: the four width tiers, the wrap-aware erase
arithmetic, the stty/dd/od raw key reader, the panel-height bookkeeping
and the hand-written redraw differ. curses owns all of it, and the alt
screen plus absolute addressing makes the desync class behind 608b022,
4210f3b, 93fc5e0 and 3c4f720 unreachable.
The sub-category taxonomy is NOT duplicated in Python: it travels in the
state dump, still sourced from __config_settings_subcats. The category,
Sponge and Paths row tables move into Python, consolidating the two
copies the fish renderers kept.
Dependency: python3 with curses. Stdlib on Arch, Fedora and a full
Debian/Ubuntu python3; python3-minimal alone lacks _curses. The launcher
checks for both and names what is missing. Called out in the README.
Verified: 416/416 assertions, plus a live end-to-end in a sandbox HOME
confirming the Universal page writes universal scope only (U1/G0) and the
Session page global scope only (U0/G1).
Add scripts/config-settings-tui.py, a stdlib-curses prototype of the
config-settings interface, plus a gate that runs its --self-test.
The backend is stubbed: values live in an in-memory dict and nothing is
read from or written to fish variables. This is here to evaluate the
render engine and the interaction model before committing to a rewrite.
Why curses rather than more ANSI arithmetic:
- No flicker, structurally. curses diffs its virtual screen against the
physical one and emits only the changed cells, which is what
__config_settings_diff_redraw.fish reimplements by hand.
- Alternate screen plus absolute addressing. Stray output cannot desync
the display, so the bug class behind 608b022 (fish's read prompt),
4210f3b (a shadow warning on stderr), 93fc5e0 and 3c4f720 (line wrap
breaking the erase height) cannot occur at all.
- Resize is a repaint rather than wrap-factor arithmetic.
- Overlays, panes, live filtering and mouse input cost a few lines each.
The layout departs from the current single panel: a page sidebar with a
live filter on the left, a scrolling detail pane on the right, a help
overlay on '?', and mouse selection. Sub-category drill-down, the
tri-state badges and the Sponge/Paths value rows all carry over.
Dependency note: python3 with the curses module. That is stdlib on Arch,
Fedora and a full Debian/Ubuntu python3; python3-minimal alone does not
carry _curses, so the test asserts the import.
The prototype is not wired into config-settings and nothing existing
changed.
Comments in tracked files pointed readers at AGENTS/specs/*.md,
AGENTS.md, and JOB-BRIEF-FINDINGS.md -- all gitignored, transient
dev notes not part of the base repo. Rewrote each to be self-contained
or point at tracked docs (docs/fish-config.md) instead.
Section 5 (function manpages) is pandoc-rendered verbatim, so a backtick
there is a literal character on the page, not markup. Nine EXIT STATUS/
ARGUMENTS lines across check_fish_deps, lock, cleanup, claude-pr,
claude-docs, dops, ports, screensleep, and steam-dl quoted a command with
backticks; reworded to plain text matching each function's own DESCRIPTION
style.
Fixes docs/verify-manual.py's test_concat_section_five_stays_verbatim,
failing in CI since before this branch (pre-existing on main, confirmed
against the commit before PR #133 merged).
- Print the missing exit-repaint after the inline editor's
__cs_dispatch_draw call (was silently changed to capture-only earlier
in the branch; this call site was missed, blanking the panel on
commit/cancel of an inline edit).
- Hoist (count $prev_edit_frame) out of a quoted math string in the
inline editor's per-keystroke redraw -- fish doesn't expand a command
substitution there, so math silently errored.
- Add a >= 52 column floor to both diff-path guards: below the
narrowest tier's own 52-column box width, lines wrap and the diff
path's one-physical-row-per-logical-line walk corrupts the display.
- Reword a stale test comment that described panel_h as mirroring a
hand-set constant in __cs_dispatch_draw; it derives panel_h from real
output now.
- Declare prev_edit_frame with -l alongside edit_frame instead of a
bare set, matching the file's convention.
- Move prev_frame's declaration to its point of use instead of an
empty top-level placeholder, matching old_h in the same block.
Root-cause fix in the shared boilerplate template (~/.config/.user-dots/git/gitignore),
same tier as .claude*/.gemini*/.antigrav*. Drops the manual one-off .agents
line; re-stamped this repo's boilerplate block to the new template hash.
__fish_config_sync_logging carried its own inferior copy of the
paru/yay wrapper generator (tee-based, no PTY, no progress-bar
rendering, hard-coded /usr/bin/paru|yay) alongside the canonical
version-6 generators in conf.d/paru-wrapper.fish and
conf.d/yay-wrapper.fish. Both wrote the same file with different
version markers and the same misattributed provenance comment, so
whichever ran last won and a subsequent C5 toggle would flip it back.
See startup-latency-JOB-BRIEF-FINDINGS.md §2.
__fish_config_sync_logging now delegates entirely to the canonical
generators instead of carrying a copy: they already resolve the real
binary via __fish_real_command (never /usr/bin-assumed) and
independently gate on their own C2/C5 keys, covering both the
enabled-regenerate and disabled-remove cases.
One behavior change falls out of delegating rather than special-casing
around it: a wrapper is no longer generated when C2 (paru-autoexec /
yay-autoexec) is disabled, even if C5 logging is on. The removed
sync-logging copy never checked C2, so it could reinstall a wrapper
the user had explicitly turned auto-exec off for.
Adds functions/_fish_source_scoped.fish: a small helper that runs
source inside its own function-call boundary. source itself runs in
the caller's scope, so a bare return inside a sourced conf.d guard
(both files have several) would otherwise unwind whatever function
called source directly -- verified with a minimal repro before relying
on it. Routing through this helper contains the return to just that
call, so calling paru's generator and then yay's actually reaches the
second call.
Manually verified end-to-end in an isolated HOME/XDG sandbox with a
stubbed paru/yay: enable generates both v6 wrappers, disable removes
both and drops the sentinel, re-enable regenerates them and clears the
sentinel.
tricks.fish is sourced twice per shell on CachyOS: once by the conf.d
autoload, once forced by config.fish to re-win over the distro's own
tricks.fish (measured 4.55ms for the second pass, see
startup-latency-JOB-BRIEF-FINDINGS.md §1). The bang-bang functions,
aliases, and history override further down need to re-run on both
passes since those are what re-assert over the distro config, but the
PATH/MANPAGER setup does not.
Gates fish_add_path and the type -q bat probe behind a once-per-session
global, guarding only that block. Everything else in the file, and the
coupling with config.fish's own cachyos-tricks guard, is unchanged.
Fills the gaps recorded in JOB-BRIEF-FINDINGS.md for the functions
converted to header-driven --help: 16 argument-less functions gain an
EXIT STATUS section (check_fish_deps, claude-docs, claude-pr, cleanup,
fast, fzf-update, gip, gip4, hist, limine-edit, lock, ports,
screensleep, steam-dl, swapstat, tmux-clean), and 8 functions that
already document ARGUMENTS gain EXIT STATUS too (lD, lsr, lss, lstree,
lt, ltr, lx, qr).
Not touched: gip6, ld, parur, sudo-toggle, upgrade, the JOB-BRIEF's
'missing ARGUMENTS' group. Re-checked their bodies against that claim
-- none of the five take a positional argument ($argv only appears
forwarded to the --help check), so an ARGUMENTS section would document
something that doesn't exist. All five already have EXIT STATUS.
The man-page comment header was separated from the function line by a
blank line -- the only file in functions/ with that gap. Cosmetic, no
runtime effect (manualtools and the help-flag renderer both tolerate
it by walking past a blank separator). See JOB-BRIEF-FINDINGS.md §2;
the renderer's tolerance for this case is left in place deliberately,
it is not dead code.
dops.fish defined `docker`, not `dops`. dops was never defined; docker
was only conditionally defined as a side effect of the failed dops
autoload, so its behavior could silently change mid-session. See
JOB-BRIEF-FINDINGS.md §1.
- functions/dops.fish now defines dops: a real enhanced `docker ps`
listing (custom Names/Image/Status/Ports table), with its own --help.
- functions/docker.fish is a new file holding the ps-redirect wrapper,
fixed to actually call dops (previously called the still-undefined
dops from inside itself).
- Bare `docker` with no arguments no longer falls through an
if-with-no-else (the fish false-zero, AGENTS.md standing gotcha #5)
and does nothing; it now runs the real docker binary, which prints
its own usage.
- tests/functional.fish: updated the now-stale comment explaining why
the help-flag check resolves the real function name instead of the
file stem.
A byte-identity gate CI never runs will rot, and a rotted gate is worse
than no gate. Adds the render harness as Phase 4, in the same shape as the
vault suite: its own process, its own sandbox, no loaded config needed.
Kept to one self-contained block so it can be dropped or re-applied by
hand if the runner is restructured. The functional suite's 317/317 count
is untouched; the render cases report separately.
Runtime escape-presence check over 24 user-facing functions.
Deliberately not a static grep for __fish_palette: measured on a broken
logs.fish whose --help block lost its declarations without gaining a call,
`fish -n` exited 0 and `grep -c __fish_palette` returned 1 while the help
output went 431 B -> 150 B with every escape stripped. The full suite was
green too. Only running the function and looking for an \e byte catches it;
that demonstration is recorded as a comment above the test.
Verified red as well as green -- deleting the __fish_palette call from
functions/mkcd.fish yields:
--help lost its colour: mkcd
FAIL test_functions_keep_their_palette
16/17 passed
fish_prompt.fish is excluded by name (its own hex palette); qc is excluded
because its --help shells out to aichat, which CI lacks.
14 cases. The production registry has 65 entries all carrying exactly one
tag and no always/* anywhere, so these three documented semantics are
unreachable from real data -- the synthetic keys/values table is the only
way to reach them. Reasoning recorded at the fixture.
Also pins the degenerate no-slash tag and reaches C5 through
__fish_config_op_enabled, which is the path production code takes.
c_rst/c_txt -> c_reset, c_ttl -> c_head, c_bold -> c_cmd, c_primary -> c_arg
across 67 interpolation sites (c_rst 53, c_primary 10, c_bold 2, c_ttl 1,
c_txt 1). Each maps to a variable holding identical bytes, so output is
unchanged. Unlike the 33 structural conversions this edits text that
renders, so it is gated on its own per-file byte-diff against main:
ok logs --help (431 B out, 0 B err)
ok mkcd --help (437 B out, 0 B err)
ok qc --help (936 B out, 0 B err)
ok rand_string --help (883 B out, 0 B err)
ok smart_exit --help (265 B out, 0 B err)
ok mkcd (437 B out, 0 B err) <- no-args error path
c_accent is deliberately NOT merged into c_ok -- both are (set_color green)
but a role is a semantic slot, not a colour. See JOB-BRIEF-FINDINGS.md.
logs.fish needed two calls (the C4 guard block and the --help block, both at
8-space indentation); it is the only multi-run file in the repository and the
exact trap a depth-deduplicating converter falls into. logs.fish also declared
c_bold without ever interpolating it -- that declaration is simply deleted.
bd-pull, branch, check_fish_deps, claude-docs, claude-pr, fast, poke, qr
and parur take the standard call site. fish-deps instead routes -h/--help
to its existing __fish_deps_help, which previously answered only via the
unknown-subcommand path, printing "Unknown subcommand: --help" and
exiting 1.
This completes the 40 conversions and lands
test_every_user_facing_function_has_help -- acceptance criterion 6, the
check that fails when a new user-facing function ships without help. It
was developed red against the pre-conversion tree and reported exactly
the 40 names of the design's CONVERT table:
bd-pull bkg branch check_fish_deps claude-docs claude-pr cleanup
fast fc fish-deps fzf-update gip gip4 gip6 hist lD ld limine-edit
lock lsr lss lstree lt ltr lx parur poke ports qr sbver screensleep
split spwin steam-dl sudo-toggle swapstat tab tmux-clean upgrade
wake-lock
each as "<name>: no -h/--help handling and not in $__help_exempt", with
the guard exiting 1. The count fell 40 -> 32 -> 24 -> 17 -> 10 -> 0
across the conversion commits. It is committed green so every commit on
this branch passes the suite.
$__help_exempt is the single machine-readable exemption record; a second
assertion fails if an exempt name stops being a published function, so a
rename or deletion upstream cannot silently exempt nothing.
8 cases on the real __fish_config_op_logging name. AGENTS.md records this
as a deliberate special case agents keep trying to 'fix' out; three of
these cases exist specifically to turn that into a test failure.
Includes the three subcategory cases proving the opt-in is inherited
through chain[-1] rather than special-cased per subcategory.
25 duplicated declarations replaced by 7 calls. Completes the 33 structural
conversions: 167 declarations removed, 33 calls added, and --structural
confirms every one of the 33 diffs is declaration removals plus inserted
calls only -- no rendering text touched.
functions/y.fish is the one file in the repo with no trailing newline on
main; its original file ending is preserved rather than normalised.
13 cases on invented variable names, so nothing ambient can perturb them:
default-on, explicit truthy/falsy, unrecognized-defers, subcategory
overriding the category in both directions, and the four cases that
together pin the master as an off switch only.
spwin, tab, hist, bkg, wake-lock and fc take the standard first-arg-only
call site, so `wake-lock rsync --help` still runs rsync.
split takes --help only: its own ARGUMENTS documents -h as --horizontal,
so a literal test replaces the renderer's own flag check. Verified that
`split -h` still selects a horizontal split and never prints help.
21 cases: a precondition asserting the fork's registry is loaded, then
truthy/falsy/unset/empty/unrecognized/no-argument/list.
Runs isolated, which is what lets these cases manipulate real guard
variable names without being able to reach the user's universal variables.
gip, gip4, gip6, ports, swapstat, sbver and steam-dl. All ignored $argv,
so --help previously ran the query or the launcher. sbver keeps its own
--brief flag: only argv[1] is inspected and --brief is not a help flag,
so the body still runs for it.
Width tier, title border, boolean badge, cursor cell and row line now come
from __config_settings_frame. The type badges (PATH/INT/LIST/STR) stay
here -- they are this page's own vocabulary, used nowhere else -- and so
does the STR default arm, which covers a user-settable value rather than
being dead code.
Introduces the `shorten` fit policy: these fields hold arbitrary user
values and want an ellipsis, unlike the toggle page's per-tier text. The
inline editor keeps `pad`, because its field is already length-constrained
and carries a reverse-video caret whose escapes string shorten miscounts.
The panel stays exactly 16 lines -- chrome(6) + nrows + blanks -- so
config-settings.fish's panel_h and its erase are untouched.
Rendering unchanged: 377/377 render cases byte-identical, golden untouched.
Code lines 123 -> 98 (-25).
44 duplicated declarations replaced by 8 calls. Output strings untouched.
fish-deps, upgrade and wake-lock have no --help path and are deliberately
NOT added to the harness case list -- upgrade and wake-lock have side
effects, and runtime coverage is not worth mutating state during tests.
They are covered by --structural, which proves mechanically that no
rendering line changed.
lD, lsr, lss, lstree, lt, ltr, lx and ld. None shadows a real binary, so
there is no disabled-fallback contract to honour, and `eza --help`
documented eza rather than the preset that is these functions' entire
content. First-arg-only interception leaves `lt -la --help` passing
through to eza untouched.
Spawns one non-interactive child against the sandboxed config and asserts on
what loaded -- abbreviations, key bindings, bang-expansions, the C5 event
handlers and the tailscale completion machinery must all be absent. Exit
codes name which guard regressed. No wall-clock assertions, so it cannot
flake.
Width tier, title border, badge, cursor cell and row line now come from
__config_settings_frame, and the hand-verified title dash count
(iw - L - S - 22) is derived from the segment's visible width instead.
Introduces the `cut` fit policy, which is this page's documented
divergence from the category list: its labels and descriptions are static
data from __config_settings_subcats rather than per-tier authored text,
and several exceed the narrower tiers' fields. `string pad` only ever
grows a string, so they are truncated before padding. That reason now
lives in two places -- the frame's NOTES and each call site -- and the
DESCRIPTION block stating it here is unchanged.
Drops label_w and desc_w, both left assigned and never read once the
frame derives the field width; the comment recording the 13-wide label
field and how the description field absorbs it stays.
Rendering unchanged: 377/377 render cases byte-identical, golden untouched.
Code lines 85 -> 49 (-36).
27 duplicated declarations replaced by 5 calls. Output strings untouched.
Four of these five files have no --help path, so the byte-identity harness
cannot reach them. Covered instead by driving the real TUI under a pty on
both the baseline and converted trees with an identical paced keystroke
feed (down x3, Tab, Enter, Esc, Tab, down, q):
9 redraws, 15068 bytes, byte-identical on both sides
c_sel (ESC[35;1m) x9, c_hi (ESC[37;1m) x8, c_head (ESC[36;1m) x9
all four draw helpers reached -- draw, pagetab, draw_subcat
("cascade default", "(category)"), draw_value ("Allow prev")
These eight ignore $argv entirely, so passing --help ran the command
instead of describing it. The new check shadows every external binary
they reach with a recording stub on PATH and fails if anything is
invoked. Before the fix it reported, verbatim:
cleanup --help EXECUTED: pacman -Qtdq
fzf-update --help EXECUTED: git clone --depth 1 https://github.com/junegunn/fzf.git /tmp/.../.fzf
limine-edit --help EXECUTED: sudoedit /boot/limine.conf sudo limine-enroll-config sudo limine-mkinitcpio sudo sbctl sign-all
lock --help EXECUTED: loginctl lock-session
screensleep --help EXECUTED: busctl --user call org.kde.kglobalaccel ... invokeShortcut s Turn Off Screen
sudo-toggle --help EXECUTED: sudo stat -c %s /etc/sudoers.d/nofail-toggle sudo tee /etc/sudoers.d/nofail-toggle
tmux-clean --help EXECUTED: tmux list-sessions -F #{session_name} #{session_attached}
upgrade --help EXECUTED: paru -Syu --noconfirm
cleanup's log line is the read that precedes `sudo pacman -Rns $orphans`,
which the stub suppressed by returning no orphans; on a real machine with
orphans present the removal ran.
Each now answers --help from its own comment header. The call site is the
first statement of the body, above the C4 guard, so help stays reachable
when the component is disabled and nothing side-effecting runs first.
run-tests.fish globs tests/test-*.fish and runs each in the mode the suite
declares in its own header. Isolated is the default and no typo can
promote a suite to in-session: detection is case-insensitive so a
near-miss is caught, the value comparison is exact.
In-session suites share one sandboxed session; isolated suites each get a
--no-config child with temp XDG dirs. Counts come back through a file so
output keeps streaming.
functional.fish becomes test-session.fish, its 15 predicates rewritten as
check calls. 332 assertions, unchanged per-phase.
Width tier, title border, badge, cursor cell and row line now come from
__config_settings_frame. The per-tier description sets stay here -- they
are this page's data, authored to fit each tier's field exactly -- and are
selected by width rather than by re-testing $COLUMNS.
Rows pass the `pad` fit policy explicitly. That is a decision, not a
default: `cut` would be a byte-for-byte no-op on these strings today and
would silently discard the property that they are tuned to their field.
Drops c_hi, which was assigned and never read.
Rendering unchanged: 377/377 render cases byte-identical, golden untouched.
Code lines 114 -> 80 (-34).
The helper is a new file, so its diff is entirely additions and can never
be "purely structural". It declares colours rather than rendering any, and
tests/functional.fish asserts its 12 roles directly.
docs/fish-config.1 is left for CI to regenerate: the local pandoc is 3.10.2
against CI's 3.1.3, so rebuilding it here emits ~4700 lines of formatter
churn unrelated to this change. The component registry rebuilt identically.
The width tier, title-border arithmetic, ON/OFF/DEFAULT badge, cursor cell
and table row are currently hand-copied across the three draw functions.
This adds them once, with the two geometry identities derived rather than
hand-maintained: a row's chrome is a fixed 21 columns, so field_w is
iw - 21 - label_w (reproducing both iw-33 and iw-34), and a title border is
dashes = iw - visible(segment) - 1 (reproducing all three of iw-23,
iw-len-3 and iw-L-S-22).
The frame owns no page height. Every verb prints exactly one line or
fragment, so the fixed-16 category and value pages and the dynamic
7+n sub-category page keep their heights, and config-settings.fish's
erase is unaffected.
No caller yet, so rendering cannot move: the golden's existing page
section is byte-identical (verified with cmp -n over its previous size)
and the file only gains frame-verb cases appended after it.
Follows the relocation out of conf.d/. The completions/ branch of the file
tree is expanded from the real directory at build time, so it needs no
hand-written children. Generated docs are regenerated separately.
A missing or label-less header must still print and exit 0. Returning 1
would hand control back to the caller's body, which for upgrade(1) is a
full system upgrade.
Both fixtures reach the renderer's bottom `count $out -eq 0` fallback,
not the unreadable-source branch. Mutating that fallback to `return 1`
turns the test red with:
headerless executed its body despite --help
malformed executed its body despite --help
The mutation was reverted before this commit.
check/section/report and the counters move out of the vault suite
unchanged. report also writes its counts to $FISH_CONFIG_TEST_COUNTS so a
driver can aggregate without parsing stdout, and ends on an explicit
boolean per AGENTS.md item 5.
All 317 vault assertions and every fixture helper are untouched.
Neither file defines a function or sets a global; their only effect is
writing ~/.local/bin/<tool>, which every interactive session does anyway.
Combined 10.7 ms off every fish -c.
__fish_config_sync_logging ran on every fish -c, mkdir+touching the C5
sentinel on disk from every subshell. Its consumers — the Kitty watcher and
the paru/yay wrappers — are interactive-context, and every interactive shell
still reconciles the state.
Declared --no-scope-shadowing with a bare set, so the 12 colour roles land
in the caller's scope under the same short names the consuming functions
already interpolate. Keeping the names means the conversion never edits an
output string in 33 of the 38 consumers.
No consumer is converted yet; byte-identity harness still reports 29/29.
run-tests.fish executes under the config it tests, which shadows cp, rm
and cat. The real hazard is cp: the config aliases it to 'cp -i', which on
a non-empty destination reads EOF in a non-interactive runner, silently
skips the copy and exits 0 -- a sandbox missing config files, reported as
success.
rm -rf and cat were measured and behave correctly as-is (the rm wrapper
bails to command rm on any non-recursive flag, so -rf really deletes and
does not trash). Prefixed anyway: a test runner must not depend on the
configuration under test.
The --on-variable PWD handler backgrounds a git fast-forward. A script that
cd's was firing it, which is also where AGENTS.md Task #4's credential
prompt could surface from a background job.
fish_color_* is consumed only by the syntax highlighter. The guard sits
below the existing cleanup branch so stale-FZF_DEFAULT_OPTS cleanup keeps
running where it does today; the FZF value itself is a persisted universal
and survives regardless.
Parses a function's own man-page comment header at call time and prints
it as a help menu on stdout, so the documentation that already generates
Section 5 of the manual becomes reachable from the shell.
Reads the .fish source rather than the generated docs/fish-config.md, so
it cannot go stale between a header edit and a docs rebuild. Walks
backwards from the `function` line to collect the header, which resolves
multi-header files (fish-deps, gi, y) without reimplementing
manualtools._block_identity.
Returns 1 only when argv[1] is not a help flag; every other path prints
and returns 0. A return of 1 hands control back to the caller's body.
Nothing calls it yet.
The suite ran under a plain `fish`, which loads the user's real
~/.config/fish and their universal variables -- this repo doubles as that
config. A test manipulating a guard variable could erase a real universal
variable out of the running shell.
Override XDG_CONFIG_HOME/XDG_DATA_HOME and pass --no-config. HOME stays
real on purpose: overriding it makes the suite's two hermeticity
assertions vacuous. Reasoning recorded at the call site.
Vault suite still 317/317 with byte-identical stderr.
Defines fish_prompt only. The guard precedes the op-guard and the type -q
PATH scan so both are skipped in scripts. Scripts fall back to the repo's
autoloadable functions/fish_prompt.fish, which nothing invokes anyway.
Compares rendered stdout and stderr of 29 colour-bearing cases between a
pristine baseline ref and the working tree, in isolated XDG_CONFIG_HOMEs
that carry the gitignored fish_variables so the opinionated guards resolve.
Two traps this harness exists to avoid, both of which silently produce a
meaningless comparison rather than an error:
- `git archive main` omits fish_variables because it is untracked. Without
it __fish_config_op_enabled is unresolvable and every guarded function
short-circuits, so all cases render empty and trivially "match".
- `qc --help` shells out to aichat and never reaches its colour path
unless aichat is on PATH; the harness stubs it.
Thirteen lines, every one a `complete -c cheat` registration, sourced on
every shell start from the wrong directory. Startup cost was already ~0
because its command substitutions are lazy, but completions/ is where fish
expects the file and the move is free.
The Cobra-generated block ran `complete --do-complete "tailscale "` to flush
pre-existing completions before erasing them, which executed the tailscale
binary. From completions/ it has no job: fish autoloads only the first match
on $fish_complete_path and the repo's completions/ precedes the vendor dir,
so the vendor file is never sourced.
Verified byte-identical completion output across four probes with the vendor
file present. A comment at the deletion site records the reasoning.
conf.d/tailscale.fish is 252 lines of Cobra-generated completion that fish
sourced on every shell start, and its self-priming block executed the
tailscale binary to warm the completion cache. completions/ is the directory
fish autoloads on first <TAB>.
Measured: 19.2 ms off both interactive and non-interactive startup.
The three config-settings draw functions are hand-tuned layout code whose
field widths, dash counts and pad targets are arithmetic on the width tier.
Any refactor of them has to be byte-identical, and nothing until now could
prove that.
Renders all 356 page/width/scope/cursor-row combinations -- every page at
COLUMNS 100/88/84/70, both scopes, cursor on every row, plus the inline
editor -- and byte-compares against a committed baseline.
The golden holds raw output: set_color escapes and box drawing exactly as
emitted, plus the wrap-aware \e[<N>A\e[J erase config-settings.fish would
emit for each panel, and per case the declared panel height against the
measured line count. Nothing is normalized; the gate is cmp(1) and a
one-space change anywhere fails it. Proven by four deliberate mutations,
one per draw function plus a panel-height change, each caught and reverted.
Runs entirely inside a throwaway HOME/XDG_CONFIG_HOME sandbox: the fixtures
must be real universal variables, and this repo doubles as a live
~/.config/fish. fish --no-config cannot be used, as -N silently degrades
set -U to global scope. Every utility is called through `command`, since
the config itself shadows rm, cat and mkdir and aliases cp -i.
AGENTS/ is gitignored upstream; a tracked file there pollutes
git diff main..work, which is what the user reads when choosing
which job to merge. Spec stays on disk, browsable, out of history.
Design for making the man-page-style comment header above each function
reachable at runtime via -h/--help, instead of hand-writing 40 more menus.
One renderer (__fish_help_header) parses the .fish source at call time and
prints the header to stdout; each call site is a single line. Audits all 79
published functions that lack help today into 35 shadow/pass-through exempt,
4 prompt-hook exempt, and 40 to convert, with a one-line reason each.
Corrects the baseline counts (109 published functions, 30 with menus, 79
without) and records two pre-existing defects found while auditing.
Note: AGENTS/ is gitignored upstream, so this file is force-added.
UnoCSS's .i-pajamas:gitea rule is unlayered CSS; our override lived in
@layer starlight.core, and unlayered rules always beat layered ones
regardless of specificity or source order. The Gitea icon has silently
stayed at UnoCSS's 1em default since it was first added -- confirmed via
computed style in the browser, not just reading the stylesheet source.
!important restores the override across the layer boundary.
Also drops the GitHub icon from 2x to 1.5x per visual feedback.
pandoc wasn't available when this branch's earlier commit ran
build-manual.py --concat; regenerate docs/fish-config.1 from the
current docs/fish-config.md now that it is.
Adds a GitHub social icon to the docs site header alongside the existing
Gitea one, and documents in the README's Contributing section that
git.rootiest.dev is the base repo while the GitHub copy is a one-way
mirror, so forks/issues/PRs should go through Gitea.
Adds Testing, Contributing, Attribution, and License sections to the
manual/man page/site, sourced directly from README.md via a new
`<!-- README: Heading -->` placeholder mechanism in build-manual.py, so
the README stays the single source of truth for those sections instead
of a hand-maintained copy drifting out of sync.
Also converts docs/manual/00-table-of-contents.md from a hand-typed list
to a generated one (mt.walk()-driven), fixing a numbering drift where
Components Reference was omitted and every section after it was off by
one relative to its own manTitle.
Five fixtures forced a failure with chmod 500 on a parent directory. That
is silently useless for root: uid 0 bypasses the mode bits, the operation
succeeds, and a test asserting a failure path then reports the tool as
broken rather than the injection as ineffective.
CI runs the suite as root inside a container, so 21 checks failed there
while passing for every developer and every reviewer -- the same shape as
the git-identity gap in the previous commit. A fixture that quietly stops
injecting is worse than one that never existed: it reads as coverage.
Shim the single command each failure hinges on, matched by a path fragment
so nothing else in the run is disturbed. A command that exits 1 on purpose
does so for every uid. Which command matters: ensure_symlink removes an
existing link before it creates the new one, so the two adopt fixtures
have to fail at that rm to leave the live link in place, and shimming ln
would be too late. The restore fixture deletes the link first and so does
hinge on ln, and the failing --remote fixture hinges on git set-url.
The one remaining chmod 500 asserts a success, not a failure, and its real
proof is the direct assertions on where the stash landed.
Reproduce the root case locally without a container:
unshare -r fish tests/test-agents-vault.fish
Verified: 296/317 as root before, 317/317 after; 317/317 unchanged as an
ordinary user; and neutering the shims reproduces exactly 296/317, the
count CI reported.
The suite was hermetic against $HOME and ~/.claude but not against git
config. new_repo set an identity on the repos the tests create; nothing
set one on the repos the tool creates -- the scaffolded vault and the
AGENTS/ sub-repo. Those inherited a global user.name/user.email on a
developer machine and committed fine, so the gap was invisible to every
local run and every review; on a runner with no gitconfig they died with
"Author identity unknown", and the suite reported the tool own correct
"nothing recorded" handling as 71 failures.
Supply the identity through the environment, which reaches the git calls
inside agents-vault and agents-init as well as the ones the tests make.
Pin commit.gpgsign off for the mirror-image reason: a developer with
signing enabled would otherwise have tool-created repos reach for a key,
and a hardware token would prompt for a touch partway through the run.
Pin init.defaultBranch because the rebase fixtures build an upstream and a
clone and need the two to agree on a branch name. A global saying main and
a bare default of master disagree, and the fixture then fails to create the
rebase the test is about, reporting a tool failure that never happened.
Verified with GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_SYSTEM=/dev/null:
267/317 before, 317/317 after; unchanged at 317/317 with a normal config.
The connect bound was delivered by injecting GIT_SSH_COMMAND, and an
environment variable outranks git's core.sshCommand -- so the guard,
which read only the environment, did not merely miss a configured ssh
command, it overruled one. A vault remote reachable only as
`ssh -i ~/.ssh/vault_key` failed to authenticate on every push, autopush
and --push alike, for the sake of a ten-second timeout. Both spellings
now count, and `set -qx` rather than `set -q` on the environment side so
an unexported fish variable -- which git never sees -- does not leave the
push with neither the user's ssh command nor a bound.
The agy knowledge walk appended each find with `set -a`, which rewrites
the whole variable every time; 500 files cost 21ms but 20,000 cost 58s,
on a path that runs in front of every agent launch. The walk now prints
NUL-separated and the list is built once, which is flat: the same 20,000
files take 707ms. NUL rather than newline because a filename may legally
contain one. What the walk collects, and its symlink and dot-led
semantics, are byte-for-byte unchanged.
Autopush is bounded by timeout(1) alone, so without it the launch path
was quietly back to an open-ended network call. It now says so and skips
the push instead; --push was never wrapped and is unaffected.
The agy knowledge allowlist walked the store with `**` and copied with
plain cp, so a symlink inside the store was both followed and dereferenced.
The extension rule still bounded what kind of file was collected, but not
whose: a link to a home directory hands over settings.json, CLAUDE.md and
every cached .json in it, and those reached a commit. A link to / made the
walk itself unbounded, on the path that runs before every agent launch.
The tree is now walked a level at a time and nothing that is a symlink is
followed or copied.
Autopush had the same shape one layer out. Neither GIT_TERMINAL_PROMPT nor
GIT_ASKPASS closes a socket, and git has no connect timeout to set: against
a blackholed address a push took 135s with http.lowSpeedLimit and
http.lowSpeedTime set as well as without them. ssh can time itself out and
is now told to; the autopush pull and push are additionally capped with
timeout(1). An explicit --push stays uncapped, since it is watched and has
to report what a real transfer really did.
Also: scaffold /.migrate-stash into .gitignore beside /.adopt-stash, which
the comment already claimed was covered; and drop the live memory path
during a slug migration only when it is a link. Reached from the
path-derived fallback candidate it can be a real populated directory, where
rm -f correctly refuses -- but said so in rm's voice, so a --silent run that
had succeeded printed what read as an error.
Six findings from the whole-branch review, all of which end in the same
place: a backup tool reporting success while nothing was backed up.
Slug migration nested the old entry inside the new one. The clear before
the rename was gated on the destination's claude/memory subdirectory
rather than on the destination itself, so an entry that exists without
one survived, `git mv A B` moved A *inside* B, and the mkdir below
fabricated a fresh empty memory directory for the live link to point at.
The real memory ended up one level deeper than --status and --restore
ever look, and the run returned 0. That shape is not exotic: git cannot
track an empty directory, so an entry committed while its memory was
empty comes back from a clone as projects/<slug>/origin and nothing
else -- and cloning the vault is this feature's own recovery path. The
destination is now moved aside the way --adopt already does it rather
than deleted (widening the rm -rf would have destroyed the clone's
origin log), its provenance is folded into the migrated entry, and every
failure path rolls back and reports.
The launch path pulled over the network. Both wrappers call agents-vault
synchronously before starting an agent, and the pull in the shared sync
helper was unguarded once an upstream existed: against a blackholed
remote it blocked the launch indefinitely and then aborted the commit,
so an offline laptop silently stopped being backed up at all. Committing
never needed a remote, so the pull moved to the push path, which was
already opt-in for exactly this reason. A failure there now distinguishes
a real rebase conflict (rebase-merge/ or rebase-apply/ present) from an
unreachable remote instead of calling both a conflict, and both network
calls set GIT_TERMINAL_PROMPT=0 and GIT_ASKPASS so they fail fast rather
than prompt with nobody watching. The helper still refuses to commit a
rebase in progress, and leaves it standing rather than aborting one it
did not start. This also restores agents-init's pre-refactor ability to
commit while offline.
The agy knowledge copy was unfiltered. The allowlist held at the agy root
and nowhere below it, so a planted .credentials.json inside knowledge/
was committed verbatim while the documentation promised nothing new
upstream added could leak in. Only *.md and *.json are copied now --
which is what the store actually holds -- so lock files, transcripts and
conversation databases are excluded by having no business in a backup
rather than by being known about. The scaffolded .gitignore also ignored
only the SQLite sidecars and not the databases, which is worse than
ignoring neither: a torn database landed in history with the write-ahead
log that would have completed it deliberately excluded. Both changes are
template-only, on a feature that has never shipped.
agents-init reported success when nothing was committed. It ended on a
branchless `if` with no arm for a failed commit, which fish resolves to
0 -- the same false zero already fixed in agents-vault, left in the
function the refactor was rewriting. It now has the arm and an explicit
final status.
The --adopt forward-failure path with no stash left a raw coreutils `mv:`
line and no statement that the adopt had been abandoned cleanly; it is
branded like every other error exit in the function.
Tests: the suite now clones a vault with git and runs agents-vault
against the clone, instead of trusting hand-built fixtures to have shapes
git can actually produce -- that blind spot shipped both of the merge
blockers. The "present but empty" migration fixture is rebuilt as the
origin-only directory a clone leaves behind, with the hand-built shape
kept as a separate case. Reverting each fix drops the suite from 285 to
279 (migration), 261 (network), 275 (knowledge allowlist) and 283
(agents-init status).
Both wrappers stay behind the C1 guard, so disabling
__fish_config_op_aliases still passes straight through to the real binary.
Launch commits but never pushes, keeping the network and any credential
prompt off the critical path; pushing is left to the Claude Code SessionEnd
hook. agy has no such hook, so its memory lands one launch later.
The adopt rollback restored the worktree but not the index. Every move it
makes is a plain rename as far as git is concerned -- the stash move out
from under the index most of all -- so a rolled-back adopt left a
half-applied rename staged against a clean vault. No bytes were at risk
and the next ordinary run's `git add -A` healed it, but a hand
`git commit` in that window recorded the half-applied state. Both
rollback sites now re-read projects/ once the worktree is whole again,
the stash restore included. projects/ is named whole rather than the two
entries, because `git add` refuses a pathspec that matches nothing --
which one of the two always is, once it has been moved back -- and then
stages neither.
The stash itself moves from the vault root into .git/, where neither the
entry walk nor `git add -A` can reach it, so a crash between the two
moves can no longer leave junk at the vault root for the next run to
commit. A vault whose .git is not a directory falls back to the root,
which the scaffolded .gitignore now covers.
--status and --restore walked the vault with a fish glob, which does not
match dot-led names. A dot-led slug is both reachable and sanctioned: the
sibling-bare-mirror idiom (`git remote add origin ../mirror.git`) keys as
..-mirror, a dot-led host keys as .hidden.example.com-o-r, and --adopt
accepts a leading dot on purpose. Such an entry is scaffolded, linked,
committed and pushed normally, yet --status under-reported it and batch
--restore left that project unlinked, both without saying so. Both walks
now list the directory instead. The --adopt completion gains -A for the
same reason: an entry that cannot be completed reads as one that is not
there.
The now-fatal push failure is painted as an error rather than a warning,
matching its sibling on the commit path.
The header notes that --adopt does not pin a name. The slug is re-derived
on every run, so the next ordinary run migrates the adopted entry back to
the canonical key, memory and live link following. Behaviour unchanged;
only the documentation gap is closed.
Tests, 173 -> 209 checks. The whole stash branch of --adopt was
uncovered, because the existing atomicity test adopts onto a slug with no
entry at all: a successful stash-adopt and a stash-adopt whose relink
fails are both pinned now, the latter asserting an empty
`git status --porcelain` and a still-reachable live memory. The stash
location is pinned by making the vault root unwritable for the duration,
which only a stash at the root would need. agents-vault's own propagation
of a failed sync had no test at all -- the third recurrence of fish's
branchless-`if` false zero here -- so both ways it can fail are now
driven end to end: a rejecting pre-commit at the vault's own
core.hooksPath, and a real rebase conflict against a bare remote. A
dot-led entry is asserted in --status and in --restore.
A push that fails against a configured remote warned on stderr and then
fell through to the trailing branchless `if`, which resolves to 0, so
`--push` reported a successful backup while nothing had left the machine.
That is the exact loss the vault exists to prevent. It now returns
non-zero, verified against a real unreachable remote rather than a mock.
The same audit found two more false zeros in this function, both fixed:
the commit block warned about a rebase conflict and walked past it, and
swallowed a hook-rejected commit entirely (neither branch of its if/else
if matched, since the error goes to stderr rather than stdout); and
--restore reported a relink failure and then returned 0 regardless. All
three now feed one flag and the function ends on an explicit status
rather than on whatever the last branchless `if` left behind.
--adopt is now atomic. A rename that landed while the relink failed left
the memory intact at the new slug but unreferenced: the next ordinary run
found no live link, recomputed the old slug, found nothing there, and
fabricated a fresh empty entry, so the agent wrote history-less memory
from then on. No bytes were lost, but continuity was, with no automated
recovery. The live link is no longer removed first -- ensure_symlink
repins a link that points elsewhere on its own -- a contentless target
entry is moved aside rather than deleted, the origin note is appended
only after the relink succeeds, and a failed relink rolls the rename back
so the vault is exactly as it was.
The --adopt validator no longer refuses a leading dot. _agents_repo_slug
legitimately emits one for a dot-led subdomain, so refusing it made such
an entry impossible to adopt; inside projects/ it is a hidden directory,
not an escape. The traversal cases are still refused: no slash survives
the charset, and "." and ".." are refused by name.
Adds the RETURNS section the header was missing. --status prints a
structured report, which this repo's convention treats as return value
rather than as progress output.
--status reports link health, orphaned entries, and how far the vault is
ahead of its remote, which is how an unpushed backup gets noticed. --adopt
rebinds a machine-specific local-* entry by hand. --push is explicit;
autopush stays opt-in via __fish_agent_vault_autopush.
Three corrections to the planned shape:
--status is dispatched ahead of the scaffold instead of behind it. As
planned it sat after the tool install, the agy knowledge copy, and the
global memory link, so asking for a report would first sync global state
and claim ~/.claude/memory. It is now read-only and reports a missing
vault rather than creating one. The global-state block moved below the
mode dispatch so it runs only on a default or --link run; the mutating
modes still need the vault repo, so they sit between the scaffold and it.
--adopt validates its slug before using it. It is interpolated into
"$vault/projects/$slug" and handed to `git mv`, so --adopt=../../../etc
walked straight out of the vault. Only the charset the slug formula emits
is accepted, with no slash and no leading dot.
--remote captures the git exit status explicitly rather than chaining an
`or` off the block terminator. That construct does work in fish, but it
reads as the silent-false-success shape that a hook-rejected commit once
produced here, and it stops working the moment the `else` goes away.
Also pins the dangling-global-symlink case the suite never covered: for a
broken ~/.claude/memory link both -d and -e are false, so the -L disjunct
in the global-memory guard is the only thing that notices it. That is the
state a buggy earlier run left on a real machine; the test asserts it is
detected, repinned into the vault, and exits 0.
The global block runs before the per-project link and the commit, but its
mkdir and link failures returned 1 outright. Global memory is optional and
frequently absent, so a stray file or a permission problem at
~/.claude/memory would abort the per-project memory backup and its commit
for every project, on every agent launch -- a fault in the secondary
feature killing the primary one.
Both failures now warn to stderr and continue, matching the treatment the
agy copy already had; the whole global block is best-effort by design.
Continuing is safe because _agents_repo_ensure_symlink validates and
refuses before mutating anything. $changed is set only when the link
actually succeeded, and nothing is recorded that would make a later run
believe the global memory is linked when it is not.
The live-side test widens from -d to -e so a stray regular file where the
global memory directory belongs is reported on every run instead of being
silently skipped and mistaken for the absent-by-default case.
Also documents that the agy knowledge copy is merge-only: a fact deleted
upstream persists in the vault and a restore brings it back. Whether the
vault should mirror deletions is a retention decision for the repo owner;
the gap is worth stating either way.
agy partitions by conversation UUID rather than by workspace, so it has no
per-project slice and is tracked globally. Its knowledge store is copied
rather than symlinked because it sits beside SQLite databases with WAL
sidecars. Claude's global memory directory is symlinked into the vault the
same way per-project memory is, including the emergent-restore direction.
Paths are allowlisted so credentials, transcripts, and session state cannot
be swept in.
Two variables keep the tests off the real home: the new
__fish_agent_vault_claude_home overrides ~/.claude (whose memory/
subdirectory is the global one), distinct from the existing
__fish_agent_vault_claude_root, which overrides ~/.claude/projects.
Without it a test run on a machine that has a real global memory directory
would move it into a mktemp vault and leave a dangling symlink behind. The
suite now points every run at a throwaway home by default and asserts the
real paths are untouched.
cp cannot report whether anything actually differed, so the copy is only
counted as a change when it leaves the vault's global/agy/ subtree dirty.
Marking it changed unconditionally would print a --quiet summary line on
every agent launch and make the flag meaningless.
The slug-migration fallback (used when there is no live symlink to read
the previous slug from) recomputed the local-* candidate by lowercasing
the basename only, while _agents_repo_slug sanitizes it. The two formulas
had drifted, so the fallback silently found nothing for any project
directory whose basename needed sanitizing.
Extract the formula into a single private helper,
_agents_repo_local_slug, and have both _agents_repo_slug's no-remote
branch and agents-vault's migration fallback call it, so there is one
place left to drift.
Also drop two dead lines the review flagged: an unused local,
and an unreachable mkdir -p (path dirname ...) — slugs never contain a
path separator, so dirname always resolves to a directory that already
exists by that point.
Widen migration test coverage: the current-entry-present-but-empty case,
a remote URL rewrite, a remote removal, and a dirty-basename fallback
test that fails without the sanitization fix and passes with it.
Adding a remote to a previously remote-less project changes its slug. Left
unhandled, the link step repinned the live memory symlink to a fresh empty
entry and orphaned the real memory.
The previous slug is read from the live symlink target rather than guessed,
which covers a remote being added, rewritten, or removed. When both the old
and new entries hold content the migration is ambiguous, so nothing moves
and the user is directed to --adopt.
config-help resolves keywords through this hand-maintained index; the
new "Agent Memory Vault" section in 07-customization.md had no entries
here yet. Adds agent-vault, __fish_agent_vault_dir, and
__fish_agent_vault_autopush, following the __fish_scrollback_history_dir
precedent (bare variable names as keys).
The guard around the symlink step only linked when the live Claude
project directory already existed, which is exactly backwards for the
clone-onto-a-new-machine restore case: a freshly cloned vault entry
would be silently left unlinked and a starting agent would write fresh,
history-less memory instead. _agents_repo_ensure_symlink already makes
its own parent directories and is idempotent, so nothing depended on
the guard; it is removed and the link is now attempted unconditionally.
Also stop swallowing a refused or failed link as success: the helper's
exit status is now checked, and agents-vault reports its own error and
exits 1 instead of silently continuing with no link in place.
Smaller fixes from the same review pass:
- check the exit status of _agents_repo_install_tools and the
core.hooksPath git config write, instead of discarding both
- give the vmem mkdir failure a stderr message like every other fatal
in the function
- guard hostname with type -q and add it to DEPENDENCIES
- .version creation now sets changed, so --link (which skips the
commit step) reports it in --quiet mode
- reword --link's help/doc text: it still scaffolds the vault and
links memory, it only skips the final commit
- drop the unused c_dim color variable
- move the __fish_agent_vault_dir / __fish_agent_vault_autopush
documentation below Opinionated Components so its NOTE: callout
(now flush-left so it actually renders as a Starlight Aside, per
review) doesn't become the first Note aside in the page and steal
the existing test's assertions about the original 4-bullet one
Adds two tests: pre-seeded vault entry with no live directory at all
(the restore path the guard was breaking), and a forced link failure
asserting agents-vault now exits 1 instead of 0.
Creates the vault repo on demand, reusing the AGENTS version bumper and
hook shims, then links the current project's live memory directory into
its slug-keyed entry and commits.
Because the live directory becomes a symlink into the vault, backup and
restore are the same operation: a cloned vault relinks itself on the next
run in each project, with no manifest and no batch restore step.
Also fixes _agents_repo_install_tools' progress messages, which hardcoded
the literal "AGENTS/.agents-tools/" even for callers writing elsewhere:
they now name repo_dir's own basename, so agents-vault reports its own
directory instead of a false AGENTS/ path.
Renames _agents_init_install_tools to _agents_repo_install_tools now that
the vault shares it, collapses the two duplicated root-symlink blocks into
one loop, and routes the auto-commit through _agents_repo_sync so a failed
rebase can no longer be committed as conflict markers.
_agents_repo_sync fell off the end of its final if-block when git commit
failed, e.g. a pre-commit or commit-msg hook rejecting it (this repo runs
ggshield and Git-LFS hooks). fish's if construct sets status 0 when the
condition is false and there is no else branch, so a rejected commit was
being reported as success rather than as the documented "not a git
repository" exit 1 it was assumed to fall through to.
Add an explicit else branch that emits a stderr diagnostic and returns 1,
and widen the EXIT STATUS/DESCRIPTION docs to cover this path under the
existing code 1 rather than adding a fourth code, since later tasks
already consume the 0/1/2 contract.
agents-init currently swallows a failed rebase and then stages and commits
whatever is in the tree, which records conflict markers under a routine
message. No AGENTS repo has a remote today so the pull never runs, but the
vault gives these repos remotes and arms it.
The shared helper aborts the rebase, commits nothing, and returns 2. It
also redirects git's own stdout during the pull/abort: git prints
"CONFLICT (content): ..." to stdout, not stderr, so without this the
message would leak into the helper's own stdout instead of staying
diagnostic-only.
The conflict fixture commits "ours" locally before diverging, since an
uncommitted worktree change has nothing for --autostash's rebase step to
replay -- it fast-forwards cleanly and only the stash pop would conflict.
Enforces the rails the vault depends on: only directories are linked
(agent editing tools refuse to write through a symlinked file), a missing
target is refused rather than turned into a dangling link, and adopting a
populated live directory copies without clobbering.
Also fixes slug sanitization in _agents_repo_slug to apply the same
[^a-z0-9._-] → - mapping to the fallback (no-remote) branch, ensuring
local project slugs are filesystem-safe and won't leak special chars like
spaces or exclamation marks.
Keys a project by its remote rather than its path so the key survives a
machine change or a directory rename. Falls back to a path-derived
local-* key when no remote exists.
Adds a hermetic test harness that builds throwaway repos under mktemp.
The mirror section told contributors a label added on Gitea "must be
created on the mirror too -- no automation does it for you." That's no
longer true, and a stale instruction to do something by hand is worse than
none, since it invites a manual edit that the next scheduled sync would
overwrite anyway.
Describe what the sync actually does: what it creates, updates, and prunes,
that an in-use label is never deleted, the --dry-run and --self-test flags,
and the rename caveat that follows from matching labels by name. Also
record the GH_MIRROR_TOKEN secret the workflow needs and its exact scopes,
since that's the one part of this that can't be automated.
The exclusive-labels caveat below it is unaffected and stays as written.
Labels don't travel with a mirror push -- mirroring copies files, not
repository settings -- but they matter on the GitHub side anyway, because
GitHub reads the same .github/ISSUE_TEMPLATE/ files and silently drops a
labels: entry naming a label it doesn't have. Until now the only thing
keeping the two sets aligned was remembering to do it by hand, which is
exactly the kind of thing that gets forgotten and then fails invisibly.
Add scripts/sync-labels.py and a workflow that runs it daily, on any change
to the script itself, and on manual dispatch. Gitea stays the source of
truth: labels are managed there and GitHub is made to match.
- **Creates and updates** anything missing or drifted. Colors and
descriptions are normalized before comparison -- Gitea returns colors
bare, GitHub sometimes with a leading '#', and a description may be null
on one side and "" on the other -- so a steady state is a true no-op
rather than a rewrite of all 33 labels every run.
- **Deletes only unused extras.** An extra label on the mirror is removed
only when no issue or PR there carries it; one in use is reported with
its count and left alone. An unattended scheduled job must not be able to
strip a label off somebody's issue.
- **Refuses to run on an empty source**, since treating that as truth would
propose deleting every label on the mirror.
- **--dry-run** prints the plan and changes nothing; **--self-test** checks
the diff logic offline against fixtures, and gates the sync step in CI so
a broken diff can't mutate anything.
Stdlib only, so the CI step installs nothing beyond python3. The job is
gated with the same github.server_url check ci.yml uses -- without it the
mirror would queue this forever against a runner that only exists on Gitea.
Labels are matched by name, so a rename reads as delete-plus-create; the
new name is created and the old is pruned only if unused. The two forges
share no stable label ID, so a rename can't be tracked across them.
The templates were written against Gitea's schema alone, but the mirror
serves the same .github/ISSUE_TEMPLATE/ files to GitHub, where two of them
would have silently failed:
- **config.yaml -> config.yml.** Gitea accepts either spelling
(modules/structs/issue.go: `base == "config.yaml" || base == "config.yml"`),
GitHub only recognizes config.yml. Under the old name the mirror's
template chooser would have shown neither the contact links nor the
blank-issue setting.
- **bug.yaml `about:` -> bug.yml `description:`.** GitHub requires
`description` on a YAML issue form; Gitea's IssueTemplate.About carries
the comment "Using description in a template file is compatible" and
falls back to it at modules/issue/template/unmarshal.go:126. So
`description` is the one spelling both forges accept. The markdown
templates keep `about:`, which is correct for their format on both.
Both files now carry a comment explaining the constraint, so neither gets
"tidied" back into a broken state.
Also add a contact link pointing at the canonical Gitea tracker, so someone
arriving from the mirror is steered to the right place before they file,
and document mirror parity in CONTRIBUTING.md: the labels must be created
on both sides by hand, since mirroring copies files rather than repository
settings and GitHub drops a labels: entry naming a label it doesn't have.
Note too that GitHub has no exclusive labels, so the one-of rule on
Priority/, Reviewed/, and Status/ holds only by convention there.
The repo carried Gitea's stock label set with no written rule for applying
it, so labels were effectively unused. Establish the standard: every issue
and PR carries exactly one Kind/ and at least one Area/, and document what
each group means, which are exclusive, and who applies them.
Extend the taxonomy to make that workable:
- **Kind/Refactor, Kind/Chore, Kind/Performance** — the stock Kind/ group
couldn't describe a refactor, a chore, or a perf change, which is much of
this repo's history. The group now maps one-to-one onto the Conventional
Commits types already in use, so a PR's label and title agree.
- **A new non-exclusive Area/ group** over the ten subsystems (functions,
completions, config, docs, tests, CI, integrations, prompt & theme,
components, scripts). This is what makes the tracker searchable by
subsystem; Kind/ alone can't answer "what's outstanding in the docs
pipeline?".
- **good first issue and help wanted**, deliberately unscoped rather than
under Status/. Status/ is exclusive, and an issue is often both blocked
and open for someone to pick up; keeping these outside the group lets
them coexist with a real status.
Priority/, Reviewed/, and Status/ are documented as exclusive and
maintainer-applied, with the rules that keep them meaningful — no
Priority/ label means ordinary priority, Reviewed/Confirmed means actually
reproduced, and a Status/ label is removed once it stops being true.
Also add labeling to the standing PR rules in Branching & Pull Requests,
so it's visible where the rest of the PR checklist lives.
Issues had no template at all, so a report arrived in whatever shape the
reporter chose — most often without a fish version, a reproduction, or the
full error text, which is what actually stalls a bug.
Add three templates under .github/ISSUE_TEMPLATE/, beside the PR template
so the GitHub mirror offers the same set:
- **bug.yaml** — a Gitea issue form rather than markdown. Version, OS,
area, reproduction, expected and actual behavior are required fields, so
an unactionable report can't be submitted in the first place. The Area
dropdown exists because contributors without push access can't set an
Area/ label themselves.
- **feature.md** and **docs.md** — comment-guided markdown in the same
house style as PULL_REQUEST_TEMPLATE.md, since what they ask for is
open-ended prose. feature.md carries `## Acceptance criteria`, the
issue-side counterpart to a PR's `## Verification`. docs.md insists on
the docs/manual/** source rather than the generated page, which the next
CI run would overwrite.
- **config.yaml** — keeps blank issues enabled for what the three don't
cover, and links the contributing guide and the customization docs.
Each template pre-applies its Kind/ label. Document the set, the plain-
description title convention (an issue states a problem; the conventional
subject belongs on the PR that closes it), and the triage split in a new
CONTRIBUTING.md § Issues.
Gitea treats a `WIP:` title prefix as a draft marker and refuses to merge
while it's present. Verified empirically against this instance by
temporarily retitling PR #123: the API flipped `draft` to true and
`mergeable` to false, and both reverted when the prefix was removed.
The distinction from the verification merge gate is the point, so it's
stated explicitly in both files: `WIP:` means more code changes are
coming, NOT "finished but unverified". A complete branch with unticked
`## Verification` boxes is an ordinary PR — that case is already covered
by the merge gate and does not want the prefix. The two signals are
independent and can occur in any combination.
Documented as a merge rule under Branching & Pull Requests, next to the
verification gate, and in the template's title guidance where an author
picking a title will actually encounter it.
The old name implied the list was only for by-hand steps, which sat badly
with the fact that most entries in practice are programmatic — the test
suite, `fish_indent`, `docs/verify-manual.py`, CI. Dropping "Manual" lets
one list carry both kinds, and gives the checkbox state real meaning:
- **Checked** — verified, whether it ran programmatically or the author
performed it by hand.
- **Unchecked** — an outstanding manual check the reviewer still has to
perform. Left visible rather than dropped.
- **The list is the merge gate.** A PR isn't merged until every box is
checked; added as an explicit rule under Branching & Pull Requests
alongside the other merge rules.
Because unchecked boxes now block the merge, the guidance also states that
only resolvable checks belong here — one nobody can run would block the PR
indefinitely. Genuinely unverifiable caveats and assumptions go in
`## Notes`, which already existed in the optional-sections list.
Incidentally realigns with PRs 121-122, which had already shortened the
heading to `## Verification`; that part of the recent drift was right.
The repo has no issue-tracking history yet — a grep across all 122 prior
PRs found zero `Closes #N` references — so this is forward-looking rather
than derived from precedent. Establishing it now means the first PR that
does close an issue has a rule to follow instead of inventing one.
- Placement is a trailing line at the end of `## Summary`, not the bottom
of the body, because `## Manual Verification` is always last.
- `Fixes`/`Resolves` noted as equivalent; `Refs #N` for a related issue
that should stay open.
- Guidance calls out that the keyword must be repeated per issue, since a
bare `#43` after a comma links without closing.
- Lives in the template's HTML comments, so a PR with no associated issue
leaves no stray `Closes #` behind.
Also drops an unverified claim that the GitHub mirror pre-loads the
template; PRs are opened on Gitea, and the mirror is push-only.
Codifies the PR body format the repo has converged on across its first
122 pull requests, which until now lived only as an implicit pattern
agents and contributors had to reverse-engineer from prior PRs.
- **`.github/PULL_REQUEST_TEMPLATE.md`** — `## Summary`, optional `##`
sections, then `## Manual Verification` as a checkbox list. Gitea falls
back to `.github/` when `.gitea/` is absent, and the GitHub mirror reads
the same path, so one file covers both.
- **`CONTRIBUTING.md`** — new "Pull request descriptions" subsection under
Branching & Pull Requests, documenting the same three-part structure.
Section names were chosen by frequency across all 122 PRs: `## Summary`
(86) and `## Manual Verification` (63) are the clear majority. The later
`## Manual Verification Checklist` (12, PRs 90-113), `## Test plan` (11)
and `## Verification` (3, PRs 121-122) variants are drift away from that
baseline, not a newer standard, so the template restores the dominant
form. Checkboxes ship unchecked but are meant to be checked before the
PR opens, matching the 585-to-12 ratio of `[x]` to `[ ]` in merged PRs.
The heading scan matches a keyword contained in a heading, so a plural
could never reach a singular heading: `customization` found "7.
CUSTOMIZATION" and `customizations` found nothing at all. The index
lookup was exact-match, so it could not cover the gap either without an
alias per word.
Both now try the keyword as typed first, then its singular/plural
forms. Each variant is tried against every heading before the next one
is considered, so a loose plural cannot beat an exact hit further down
the document.
config-help pipes the manual through bat, which dims the backticks and
leaves the span content the same colour as the prose around it -- so a
delimiter carried no information and every span cost the reader two
literal characters. 1236 of them across the document.
Each span is now rendered bold and the delimiters dropped, in every
branch of the viewer chain:
- ov + bat, and ov alone, style the spans (bat's output wraps each
backtick in its own SGR sequence; raw Markdown is matched directly)
- bat alone flattens them on the way in instead, because bat escapes
any SGR sequence handed to it as input
- less and cat style them, less gaining -R to render the result
- man -l needs nothing; pandoc consumed the backticks at build time
Both substitutions are line-preserving, so the tail-slice that opens
the pager on a requested section still lands on it.
Two shapes reach a reader as literal punctuation rather than markup:
A backtick inside a four-space block. The block is verbatim in every
renderer -- pandoc sets it monospace, prettify() fences it for the site
-- so the backtick is a character on the page. Twelve such lines are
cleaned; each sat at the start of its column, so the alignment of the
C5 capture table and the component summaries is unchanged.
A span split over a line break. Markdown pairs it happily, but
config-help pairs backticks one line at a time, so `fish-deps\nupdate`
showed both halves. The sentence is reflowed.
Both are now enforced, the first by test_concat_section_five_stays_
verbatim and the second by test_concat_code_spans_never_straddle_a_line.
A token was typeset by whichever pipeline happened to render it: the
site marked tmux and local.fish through codespans, while the man page
and config-help marked only what the SSOT had backticked by hand. Run
the same pass in build_concat() so prose is marked identically wherever
it is rendered (549 -> 662 spans in the concat).
codespans now treats a four-space block as code. The site never meets
one -- prettify() has already turned it into a fence by then -- but the
concat keeps the indented form pandoc wants, and its contents are
verbatim: without this the table of contents alone would come out with
ov, bat, less and cat wrapped inside a code block. Section 5 is
unaffected for the same reason; its entries arrive as indented blocks
that pandoc already sets in a monospace font.
test_codespans_is_site_only asserted the opposite guarantee and was
passing only because its example, -r/--resume, sits inside one of those
newly-protected blocks. It is replaced by tests for what is now true:
indented blocks stay verbatim, prose spans reach the concat, and
section 5 carries no backticks.
The man page is left for CI to regenerate; pandoc is not needed to
build the concat.
CONTRIBUTING states doc-headers are written as plain text -- the header
is read as-is by config-help, by funcsave, and by anyone opening the
file, and docs/codespans.py adds the site's inline code spans at render
time. 22 files had drifted from that, carrying 41 hand-written spans
that reached config-help and the man page as literal backtick
characters inside an otherwise verbatim block.
The one span whose content ended in a space is requoted rather than
dropped, so "read> " keeps reading as a prompt string.
Cover the ~50 previously-unindexed headings (function reference entries
like play-media, steam-dl, bd-pull, cffetch/ffetch, config-toggle, dops,
rand_string, fish_prompt/fish_mode_prompt/fish_right_prompt, lD, mv, p,
fast/fast-cli, gip4/gip6, fzf-update, sponge_filter_secrets,
fzf_configure_bindings, ld; the C1-C6 component sub-category headings
filesystem/network/monitor/shell-tools/dev-tools,
plugin-management/pkg-wrappers/venv/telemetry/sync,
key-bindings/environment/prompt, terminal-abbrs/window-mgmt/
notifications/history-logs/pkg-upgrade, terminal-capture/
multiplexer-capture/pkg-logs, first-run/greeting-message; plus
Config Variables' "Other", the Integrations "Scrollback History", the
dependency catalog's Optional/Terminal Emulators tiers, the C0/always
override note, and "Reading the source directly").
Expanded aliases for existing headings: play-media also reachable as
video/audio/mpv/vlc, steam-dl as steam, cffetch/ffetch share fetch/
fastfetch/neofetch/sysinfo, rand_string as random/password/randomword,
gip4/gip6 as ipv4/ipv6, dops as docker-ps, ld as lazydocker, bd-pull as
beads, fast-cli as speedtest, sponge_filter_secrets as secret-filter.
Fixed two pre-existing duplicate normalized keys (key-bindings/
keybindings and man-page/manpage both collapsed to a single entry) and
repointed config-toggle from the generic config-settings heading to its
own dedicated "### config-toggle" heading now that one exists.
Judgment calls on ambiguous/repeated heading text (left unindexed, or
indexed via a distinguishing keyword instead of the literal name):
- "### Sub-categories" repeats 7 times (once per opinionated-components
overview and once per C1-C6 page); an index entry pointing at that
text always resolves to the first occurrence, so none of the 7 are
indexed under that name. Each parent (C1-C6, and the Minimal Mode
section) already has its own keyword.
- "### search" appears twice: the pkg search subcommand (kept, existing
`search` key) and the C1 command-shadow sub-category. The C1 one
isn't separately reachable for the same reason.
- "## Integrations" appears twice (Section 1 integrations writeup and
the Dependency Catalog's Integrations tier table); only the first
(already indexed) is reachable.
- Where a C1-C6 sub-category heading text collides after normalization
with an existing higher-value keyword (key-bindings, network,
notifications, venv), the new entry uses a distinguishing keyword
(bindings-toggle, network-shadow, notifications-toggle, venv-toggle)
instead of contesting the existing one.
- `prompt` now points at the fuller "## Prompt and Theme" section
rather than the one-line C3 sub-category blurb; the latter is
reachable via `prompt-toggle`.
The test/build-docs jobs target a self-hosted runner (racknerd-mini)
that only exists on the Gitea instance. When GitHub re-runs this same
workflow on the mirror, those jobs sit queued forever with no matching
runner, so the commit never gets a completed status.
Gate both jobs to skip when github.server_url is github.com, and add a
trivial github-mirror job (runs-on: ubuntu-latest, which GitHub does
provide) that only runs on the mirror, so the check completes instead
of hanging.
Function doc-headers are authored as plain text -- `config-help`,
`funcsave` and anyone opening the `.fish` file read them as-is -- so they
carry no backticks. The site inherited that and rendered `-a/--all` and
`__fish_config_op_aliases` as ordinary prose.
docs/codespans.py adds the spans at render time, as the last step of
prettify(), so only the site sees them; build_concat() (man page,
config-help) is byte-for-byte unchanged.
Recognised shapes: flags and flag pairs, `$vars`, SCREAMING_SNAKE env
vars, snake_case identifiers, paths and filenames, key chords, command
shadow chains (`ls->eza`), runs of tool names, whole command lines in a
table column of command lines, and known command names -- drawn from the
`_fdc_*` catalog in functions/_fish_deps_catalog.fish, the functions/
listing, and a standard-command list, minus the names that also read as
English.
Fenced blocks, existing code spans, headings, link targets, URLs,
component markup and <FileTree> bodies are passed through untouched, and
every rule bails out rather than guess.
Verified every claim in the Prompt and Theme section against the actual
source and corrected several inaccuracies: the Starship wrapper's missing
C3 gate, the fallback prompt's vi-mode states and segment order, the FZF
theme's real location (conf.d/theme.fish, not integrations/fzf.fish) and
color set, and the Catppuccin theme-switch example using the wrong
fish_config subcommand (choose, not save). The right-prompt Docker-context
example was rewritten to show that it's independent of exit status.
While reformatting, found that any block build-manual.py couldn't classify
as shell/table/tree fell back to plain 4-space markdown indentation, which
silently renders as squashed, unreadable paragraph text on any page that
also contains an <Aside> or <FileTree> — MDX has no indented-code-block
syntax, unlike plain Markdown. This affected 07-customization.mdx plus four
other pages. Fixed the fallback to emit a fenced ```text block instead,
since fences work in both MDX and plain Markdown; this also gives every
affected block Starlight's normal code-block styling instead of a bare grey
slab.
docs/fish-config.md is intentionally left stale here — CI regenerates and
auto-commits it from docs/manual/** on push to main.
List every file in functions/ and completions/ inline under the home
page's file tree instead of a one-line summary. The listing is read
live off disk during --site generation, so it never needs manual
upkeep, and only affects the Starlight build — the plain-text
manual/man page (--concat) still renders the compact summary.
Documents the branching/PR workflow, commit conventions, fish function
doc-header and colored --help conventions, the docs generation
pipeline, testing, and the secrets/machine-config placement rule, so
these practices live somewhere durable instead of only in commit
history and conversation memory.
Add the established c_head/c_cmd/c_flag/c_dim/c_arg color scheme to
--help (or usage-on-error) output in play-media and 13 other functions
that lacked it or used an ad hoc scheme: bkg, detach, replay, p, y,
spark, wake-lock, open-url, repo-open, dng2avif, dockup, fish-deps
(__fish_deps_help), and scrub.
Also tweak the standard itself:
- c_cmd now uses plain `set_color --bold` instead of `--bold white`,
so the command name adapts to the terminal's foreground instead of
forcing white text that washes out on light-background themes.
Applied across all functions already using the pattern.
- jobrunner's reset variable renamed from c_rst to c_reset to match
the naming used everywhere else.
A missing trailing backslash after the Thumbs.db:encryptable pattern
terminated the `set -l aggressive_patterns` array early. The AI-tool
patterns (.gemini*, .claude*, .antigravity*, .remember*) were then
executed as a bogus command instead of being appended to the array,
so scrub -a never actually purged them, and every scrub invocation
printed a spurious "Unknown command" error.
Fuzzy-filters audio/video files under the current directory via fd,
previews them with thumbnails pulled from the freedesktop thumbnail
cache (or ffprobe metadata as a fallback), and plays the selection
through the best available player: --player flag, $play_media_player,
xdg-mime default, then a short mpv/vlc fallback list. Adds mpv/vlc as
optional fish-deps entries.
The only other cd left in the workflow mixed two working directories
in one step: docs/build-manual.py --site runs from the repo root, then
npm ci/astro build need docs/site. Split into two steps so each can
use working-directory instead, keeping the whole file cd-free and
consistent with the Cloudflare deploy step's fix.
Gitea/GitHub Actions auto-groups a multi-line run: script under
"Run <first line>". With `cd docs/site` as the first line, the
collapsed log tree showed that instead of the actual wrangler deploy
command. Moving the directory change to the step's working-directory
key drops cd from the script entirely, so the group label now reflects
the command that's actually running.
workflow_dispatch already ran the whole pipeline manually, but there
was no way to fire just one job (e.g. re-run docs generation without
re-running the fish test suite) the way the old standalone
build-docs.yml let you. Add a job choice input (all/test/build-docs,
defaulting to all) and gate each job on it via `if:`, while leaving
the push-triggered path's needs: test gating untouched.
Two more sources of CI noise/fragility alongside the debconf frontend
fix: fish's install pulls in man-db/groff-base/xsel as recommends,
triggering a slow mandb rebuild for tooling nothing here uses;
--no-install-recommends skips that. apt-get update had no retry
policy, so a transient blip against the PPA mirror failed the whole
job; -o Acquire::Retries=3 gives it a few chances first.
apt-get install was probing for a Dialog then Readline debconf frontend
before falling back to Teletype on the non-interactive CI runner,
adding noise and failed-negotiation log lines to every run. Passing
DEBIAN_FRONTEND=noninteractive directly on the sudo command line (env
vars set via step-level `env:` don't survive sudo's env_reset) skips
the negotiation and goes straight to the frontend that actually works
here.
The @@ picker only listed files with no preview. It now lists both
files and directories via fd (matching _fzf_search_directory), and
shows a bat-highlighted or image-rendered preview through
_fzf_preview_file. Image previews use a kitty-graphics-protocol,
chafa, viu, timg fallback chain via the new _fzf_preview_image
helper, benefiting the Ctrl+F directory search and git-status
pickers as well since they share the same preview helper.
Adds tests/run-tests.fish (syntax lint over every .fish file, plus a
sandboxed interactive load) and tests/functional.fish (10 checks
covering XDG/PATH/CDPATH setup, key bindings, abbreviations, core
functions, exit rewiring, and the opinionated-component registry).
The sandbox copies config-relevant files into a scratch HOME/XDG tree
rather than symlinking the checkout, since this repo also serves as a
live ~/.config/fish and a symlink would let universal-variable writes
leak into the real fish_variables file.
Wires the suite into build-docs.yml as a `test` job that `build-docs`
now depends on, so a broken config can no longer get published to the
docs site. Documents the workflow in the README's new Testing section.
Binding the raw @@ chord made a lone @ an ambiguous prefix, so fish
(with fish_sequence_key_delay_ms unset) held every typed @ indefinitely
until a disambiguating keystroke arrived, breaking things like
`ssh user@host`. Binding the single @ key instead and checking whether
the current token is already a bare @ removes the ambiguity entirely:
plain @ always self-inserts instantly, and a second consecutive @
triggers the picker in place, with no forced delimiter before you can
keep typing. Vi's normal/visual modes are left unbound, matching their
existing (no-op) @ behavior.
Ubuntu 24.04's default repo only carries fish 3.7, but
docs/manual/06-dependency-catalog.md states fish >= 4.0 as a
project dependency. ppa:fish-shell/release-4 is the fish-shell
maintainers' own PPA and explicitly supports 24.04.
fish 3.7 (Ubuntu 24.04's packaged version, used in CI) rejects
'source /dev/stdin' when it's backed by a pipe, with
"'/dev/stdin' is not a file" -- fish 4.8 (local dev) accepts it.
Writing the generated registry to a real temp file sources
identically across fish versions.
The registry round-trip test spawns a real fish subprocess to verify
conf.d/__fish_config_op_registry.fish sources correctly, but the
runner image has no fish binary, so the workflow failed with
FileNotFoundError.
The wrapped description for the Enter key was indented one column past
every other description in the Navigation block. Drop the extra leading
space so it lines up at column 17 with the rest.
test_c0_tags_never_combine_with_contradiction_unwarned could never fail (its
own docstring said so) yet inflated the test_* pass count. Rename it to
warn_c0_tags_never_combine_with_contradiction, matching the file's existing
warn_* convention, and call it explicitly from main() alongside the other
three warn_* checks.
warn_functions_without_component also permanently false-positived on
functions/__fish_config_op_enabled.fish: the file's own function signature
and EXAMPLE prose contain the literal guard name, tripping the "calls the
guard" substring check against itself. Exclude the guard's own supporting
infrastructure files (__fish_config_op_enabled.fish,
__fish_config_op_cascade.fish, __fish_config_op_registry_lookup.fish) by
name -- an EXAMPLE-section-only exclusion wouldn't have worked here since
the false match is the function's own `function __fish_config_op_enabled`
definition line, not just its EXAMPLE block.
- Quote both keys and values in the generated __fish_config_op_registry.fish
keys array so a future identity/tag containing a glob-special character
(*, ?, [) can't be silently dropped by fish's set, desyncing the
positionally-paired keys/values arrays.
- Deduplicate the tag list per site in build_registry() so an identity
collision across sources (e.g. auto-pull tagged autoexec/sync in both
functions/auto-pull.fish and conf.d/auto-pull.fish) no longer produces a
duplicated tag in the committed registry.
- Add a comment to the generated file's header noting it must sort first
among conf.d/*.fish guard-callers, since that ordering is currently
implicit in the filename rather than stated anywhere.
- CI's auto-commit step now also stages conf.d/__fish_config_op_registry.fish
alongside the docs it already regenerates, so a # COMPONENT header change
pushed without a manual __fish_config_op_registry_rebuild self-heals
instead of silently drifting from what CI just regenerated.
Sub-categories were previously undocumented outside README and the
per-category reference pages. Add a paragraph to 07-customization.md (the
canonical opinionated-components page) explaining the sub-category cascade,
a short note to the 08-components-reference index pointing readers at each
category's sub-category list, and a troubleshooting note that
__fish_config_op_<category>_<subcategory> variables follow the same
check/reset pattern as category variables.
Bundled fix wave for six findings from the sub-category-granularity
whole-branch review:
- config-settings: reset in_subcat on Tab/Shift-Tab so up/down keep
routing to cur_row instead of freezing on the Sponge/Paths pages
after a drill-down
- verify-manual: _parsed_components() now delegates to
generate_component_registry.collect_components() instead of a
lossy dict.update() merge, closing a taxonomy-check blind spot on
identity collisions
- verify-manual: add test_committed_registry_matches_headers to
catch the committed registry drifting from current # COMPONENT
headers
- build-docs workflow: trigger on conf.d/** and config.fish edits,
not just functions/**
- __config_settings_draw_subcat: show (Universal)/(Session) in the
drill-down title so the persistence scope is visible before toggling
- __config_settings_draw / config-settings: mention the Enter
sub-category drill-down in the on-screen hint and --help text
- generate_component_registry: send the "wrote ..." progress line to
stderr so it no longer corrupts --concat's stdout output
Two bugs invisible to single-frame rendering, only reachable via the
interactive event loop:
- right/l and left/h resolved the sub-category variable name with
"$toggle_vars[(math ...)]"_(...) inside a quoted string -- fish
cannot expand a command-substitution index there ("Invalid index
value"), so the set never ran and varname silently kept the parent
category variable. Every arrow-key press on a sub-category row
toggled the parent category instead. Fixed by hoisting the category
variable into a plain local first, the same technique the down/j
case already used for its page index.
- __cs_dispatch_draw left panel_h fixed at 16 regardless of what it
actually drew, but the new sub-category page is n+7 lines (9-13,
always < 16). Every redraw/cleanup erase computed its height from
the stale constant, erasing too many rows and corrupting whatever
was above the panel. Fixed by having the dispatcher record the
actual printed height into panel_h after every draw, including
resetting it back to 16 on the value pages even when in_subcat is
stale from a Tab away without an intervening Escape.
Adds __config_settings_draw_subcat.fish, rendering a category's own
toggle plus its sub-category rows, sized dynamically from
__config_settings_subcats instead of the fixed 6-row category layout.
Wires the real per-category row count into config-settings.fish's
up/down handling (replacing Task 17's stub) and adds the
hyphen-to-underscore sub-category variable resolution to the
left/right toggle handlers, mirroring the translation the guard
function already applies.
Two box-drawing bugs surfaced while adapting the design doc's draft to
the real static sub-category data and were fixed rather than
transcribed: the title-dashes offset was off by 5, and several real
sub-category labels/descriptions (e.g. "Notifications", 13 chars;
several descriptions past 30 chars) exceed the narrower width tiers'
fixed field widths, so both fields are now defensively truncated
before padding to keep every row exactly iw+2 wide regardless of
content length.
overrides-tricks conflated two distinct C3 concerns under one shared site
(overrides/environment), so __fish_config_op_overrides_key_bindings off
left tricks.fish's bang-bang bindings active while abbr.fish/puffer.fish/
config.fish's equivalent sites correctly disabled -- a half-dismantled
bang-bang system per docs/manual's own atomic-gating claim. Split into
tricks-manpager (overrides/environment, matches PAGER/EDITOR/CDPATH) and
tricks-bang (overrides/key-bindings, matches abbr.fish/puffer.fish/
config.fish's bang-related sites, per
docs/manual/08-components-reference/03-c3-key-and-environment-overrides.md).
Also fixes stale prose in config.fish's top-of-file comment: the guard
signature is now <identity> [<site>], not <category>.
The site was mistagged aliases/filesystem in the prior commit. The original
code's own comment above the guarded block ("Surgically overriding the
distro config is opinionated (C3 overrides): skip it entirely when
overrides are disabled") documents this as an overrides decision, and it
gated __fish_config_op_overrides pre-migration. Retag to
overrides/environment (matching tricks.fish's own sibling site for the
equivalent action) so aliases=on/overrides=off keeps skipping
tricks.fish/ls/lt/cleanup/copy, as originally documented -- no silent
user-facing behavior change.
Adds multi-site `# COMPONENT` headers and converts every guard call site in
conf.d/tricks.fish, conf.d/abbr.fish, functions/smart_exit.fish,
conf.d/yay-wrapper.fish, conf.d/paru-wrapper.fish, conf.d/wakatime.fish,
conf.d/first_run.fish, and config.fish (9 sites across 3 categories) to the
self-identifying `(status current-function|basename) <site>` calling
convention. Regenerates conf.d/__fish_config_op_registry.fish.
__fish_config_op_enabled built the sub-category override variable name by
concatenating the tag's slug verbatim, e.g. __fish_config_op_integrations_window-mgmt.
Fish variable names cannot contain hyphens, so any hyphenated sub-category
slug (14 of the 24 in the taxonomy) silently could never be overridden --
an unset such variable safely fell through via set -q, but attempting to
set it always errored with "invalid variable name", masking the defect
since no prior smoke test exercised an explicit sub-category-level toggle.
The registry tag itself (as authored in # COMPONENT headers and the
taxonomy docs) stays hyphenated; only the derived fish variable name is
translated.
collect_components() used dict.update(), which let conf.d silently
overwrite functions/ (or vice versa) when the same bare identity
appears in both, e.g. functions/auto-pull.fish and
conf.d/auto-pull.fish. The runtime guard can only ever look up the
bare status current-function/basename string, so both call sites
genuinely share one identity and their raw COMPONENT lines must be
concatenated, not replaced.
At the default 1em (16px) it read as noticeably smaller than the
other header controls, especially next to the logo. Bumped to a fixed
1.5rem — well within the nav bar's existing content height, so the
header itself doesn't grow.
logo.svg was 56KB of unminified, high-precision path data with no
embedded raster. Running it through SVGO (default preset, multipass)
cuts it to ~20KB with no visual difference.
perf(docs-site): further minify header logo SVG. Cut to ~8.9KB with no visual difference.
The header social link used Starlight's generic `code-branch` icon.
Wires up starlight-plugin-icons + UnoCSS (Iconify) and overrides
SocialIcons to render `pajamas:gitea` for the Gitea link instead, while
falling back to Starlight's default icon set for anything else. Sidebar
and codeblock icon support are enabled but unused for now.
Explains that a matched command is actively deleted from history and
force-saved within about one prompt cycle by default, not deferred to
shell exit, and calls out sponge_purge_only_on_exit as the setting that
would change that (a killed/crashed session never triggers fish_exit).
Also hyperlinks the Fisher-managed and bundled plugin names to their
upstream repos on the Starlight site.
Reworks fish-deps' dependency classification from three tiers to five:
Required, Recommended, Optional, Terminal Emulators, and Integrations.
- Add an Optional tier for single-purpose wrapper conveniences that only
matter if you already use that specific tool (btop, dust, duf,
prettyping, go, lazygit, lazydocker, docker, yt-dlp, screen). Skipped by
`fish-deps install`/`sync` by default.
- Split kitty/wezterm into their own Terminal Emulators tier, since only
the one matching $TERM is ever relevant to a given user.
- Add --optional, --terminals, and --all flags to `install`/`sync` to
opt back into the skipped tiers, with a summary of how many were
skipped and which flag restores them.
- Fix `_fish_deps_status` marking missing Integrations as critical (red)
the same as Required — only Required is red now; Recommended stays
yellow, everything else renders as a neutral dim note.
Also fixes two bugs surfaced during dependency testing on a fresh
install:
- `fish_right_prompt` called `docker context show` on every prompt with
no `type -q docker` guard, unlike every other optional integration in
this config — on a system without docker this printed a visible
"Unknown command: docker" block on every single prompt render. Added
the missing guard, and hardened the `ld` wrapper with explicit
docker/lazydocker presence checks.
- `ov`'s catalog entry offered `cargo install ov` as its preferred
install method, but crates.io's `ov` is an unrelated crate, not the
noborus/ov pager — cargo would silently install the wrong package.
Removed the cargo path; `ov` now prefers `go install
github.com/noborus/ov@latest` (ahead of the system PM) when go is
available, since not all distros package `ov` in their base repos,
and falls back to the system PM otherwise.
The EXIT STATUS block used a single space before the ">0" row's
description, which falls below the doc pipeline's 2-space column
threshold and silently degrades the rendered site page from a table
(like rm's) to a plain indented block. Pad it to match. Also strip
trailing whitespace from two DESCRIPTION lines and add --wraps='mv'
so fish inherits real mv's completions, matching the bash/top wrapper
convention.
Add the starlight-llms-txt plugin so the docs build emits llms.txt,
llms-full.txt, and llms-small.txt alongside the regular pages, making
the manual queryable by MCP-compatible agents without depending on a
third-party indexing service.
Also bump js-yaml, nanoid, and sharp in docs/site to clear three
high-severity advisories (quadratic YAML omap parsing, a zero-size
nanoid loop, and inherited libvips CVEs) flagged by npm audit while
touching the same lockfile.
Adds jobrunner (short alias jr) for running, listing, inspecting,
re-attaching to, and terminating detached background tasks. Unlike bkg
and detach, which discard output, a jobrunner job keeps a live terminal
that survives closing the shell and can be restored later with attach.
Includes the __jobrunner_sessions parser shared by the function and its
completions, dynamic job-name completions, and screen in the fish-deps
catalog.
- Eliminate the warning about the generic 404 page being replaced, it
was intentional.
- Add a flag to the cloudflare deploy task to approve pushes from dirty
git repos, it was intentional for the dynamic build.
The agy tool uses -c and --continue natively. It does not recognize -r
or --resume. This commit allows -r and --resume to be used by
translating them to -c and --continue respectively.
Session logging is the one opinionated category that writes a persistent
record of terminal output to disk, and those logs can contain secrets.
Silent-by-default is the wrong posture for it, so C5 now defaults to off:
__fish_config_op_logging must be set to an explicit truthy value to enable
capture, and the master switch cannot enable it on its own.
Implemented as a single special case in __fish_config_op_enabled, so all
five capture components, the sentinel file, the paru/yay wrappers, the
Kitty watcher, and the config-settings TUI pick it up with no other code
changes. The existing startup sync in conf.d/logging-events.fish
reconciles the sentinel and removes the generated wrappers on the first
shell after upgrading.
BREAKING CHANGE: users relying on the previous default must now run
`set -U __fish_config_op_logging on`. Existing logs in ~/.terminal_history
are left untouched.
Updated the python site builder's regex to correctly parse file paths containing shell variables like $__fish_user_dots_path in comment titles. Also added fish_default_key_bindings to the known shell-heads list so those examples are correctly wrapped in a fenced code block rather than falling through to plain text and getting parsed as MDX headings.
Renamed 'Uninstalling / Reverting to Backup' to 'Uninstalling and Reverting to Backup' to avoid the edge cases where forward slashes cause Starlight top navigation cards to break when generating the heading slug.
Modified build-manual.py to strip punctuation and properly handle spaces/hyphens during link slug generation. This ensures top navigation link cards generated by the script actually match Starlight's URL format. Also fixed a few manual markdown links that mistakenly contained double dashes.
Replaced the minimal mode troubleshooting section with a new 'What's with the C1-C6 stuff?' heading. Included a quick-reference table for the six opinionated categories with links to their detailed customization sections, and updated the documentation index.
Converted plain text references to Markdown links across the troubleshooting documentation and index.md. Converted commands to properly formatted inline code blocks, and ensured code blocks conform to the SSOT's indented-block requirements.
Wrapped the XDG variables and PATH setup in config.fish with the C3 overrides toggle so users can fully opt out. Updated the documentation (07-customization.md, 02-path-setup.md, README.md) to reflect this. Also added a Home link to the 404 page and removed a leftover test_sidebar.js file.
Created a custom Starlight 404 page (docs/manual/404.md) that includes LinkCards pointing to common sections (Installation, Troubleshooting, Function Reference). Also updated build-manual.py to prevent '404' from appearing in the generated sidebar.
Renamed the root 'Overview' entry under 'Functions Reference' to 'Categories'. Also renamed the inner category 'Overview' entries to '{Category} Overview'. Because Starlight uses the sidebar label for the 'Next/Previous' pagination buttons at the bottom of pages, having multiple pages labeled just 'Overview' caused the button text to ambiguously say 'Next: Overview' even when linking to a new category.
Renamed the 'Path Setup' section to 'PATH Setup', formatted the prepended directories list as a Markdown table, and added a NOTE acknowledging that these paths will shadow existing system binaries of the same name. Updated verify-manual.py test since 02-path-setup now contains an Aside and gets correctly promoted to .mdx.
Fixed tables and text formatting in the Dependency Catalog and Configuration Variables pages so they render properly as markdown instead of flat code blocks. Added introductory sentences to Troubleshooting and Customization so the Starlight sub-heading navigation cards get injected at the top of the page rather than jumping below the first heading.
The sidebar previously started with 'Configuration Variables' which felt abrupt. Add a 'Home' link at the top pointing to the landing page (the one with install/functions-ref buttons). Seeded the sidebar list in build_site() so it persists across --site rebuilds.
The troubleshooting section renumbered Viewing This Manual from 11 to
12, but verify-manual.py still hardcoded the old filename
(11-viewing-this-manual.mdx) in the site promotion test. Update both
references to 12-viewing-this-manual.mdx.
Also regenerate docs/fish-config.md so the concat roundtrip test passes
with the new section ordering.
Add a new Troubleshooting section to the manual with 9 concise how-to
subsections covering uninstall/revert, Fish version requirements,
disabling logging, changing the greeting, secrets/local config, the
return sentinel gotcha, missing dependencies, Vi mode keybindings,
and minimal mode.
Renumber Viewing This Manual from Section 11 to Section 12 to place
troubleshooting before it. Update TOC and help index accordingly.
All verify-manual.py checks pass.
# Please enter a commit message to explain why this merge is necessary,
# especially if it merges an updated upstream into a topic branch.
#
# Lines starting with '#' will be ignored, and an empty message aborts
# the commit.
- test_customization_notes_render_as_aside now asserts the four NOTE
bullets live inside the <Aside> tags, not merely anywhere on the
page — a re-wrapped bullet previously still passed because the
bullet text leaked into an untouched sibling paragraph.
- TREE_BRANCH_RE no longer matches an indented/continuation branch
line (dropped the leading `[│ ]*`), so a second-level tree falls
through to verbatim rendering instead of being silently flattened
to one level. Added test_as_file_tree_rejects_deeper_trees to guard it.
RETURNS previously conflated fish's $status exit code with genuine
stdout/printed output, e.g. rm listing "0/1" as if they were print
values rather than exit codes. Rename RETURNS to EXIT STATUS across
all 83 documented functions, and reintroduce RETURNS as a distinct
label reserved for the 15 functions that actually print to stdout.
Update build-manual.py's ENTRY_HEADS to render Exit Status before
Returns, manualtools.py's SECTIONS constant, and AGENTS.md's label
order and label-usage guidance to match. Add two verify-manual.py
regression tests: EXIT STATUS bodies must never contain stray
stdout/printed language, and Returns: must always render after
Exit Status: when both are present. Regenerate docs/fish-config.md.
Every ruled table in the SSOT used one solid rule under the header
except the "Fish Universal Variables" table, which used the other
(per-column, RST-style) convention build-manual.py just learned to
also accept. Two conventions for the same thing with no reason for
the split, so convert the outlier to match the other six.
The parser keeps supporting both — the per-column style stays a
useful fallback for anyone still authoring that way — this just
makes our own SSOT consistent.
_as_ruled_table() only matched a single solid run of dashes under the
header row. The "Fish Universal Variables" table in
07-customization.md uses the other common convention instead: one
dash run per column, gapped the same as the header (RST simple-table
style) — e.g. "------ ----------". That line failed RULE_RE's
whole-line match, so the table still fell through to a code block.
Split the rule line on the same CELL_SPLIT boundary used for data
rows and require every resulting group to be a solid dash run, which
accepts both conventions without adding a second code path.
No SSOT changes needed — the source table was already well-formed,
docs/fish-config.md round-trips unchanged, confirming this is a
site-only fix.
_as_table() only detects tables whose data rows are indented deeper
than a ":"-terminated label. The "Component Reference" tables use a
different convention (header, dashed rule, rows all at the same
indent), so they never matched and fell through to a plain indented
code block on the Starlight site.
Add _as_ruled_table() to recognize that header+rule+rows shape. It
supports N columns, folds word-wrapped continuation lines into the
previous row, and backtick-escapes cells containing "<" or "{" instead
of rejecting the table outright (unlike _as_table's stricter guard,
which those tables would otherwise trip on for angle-bracket
placeholders and brace globs).
Also fixes four ambiguous rows in 07-customization.md where two
columns had collapsed to a single space, making them indistinguishable
from a word-wrapped continuation.
Rename the Starlight site to "Rootiest Fish Config" and switch its
canonical URL from the Cloudflare Pages subdomain to
fish-config.rootiest.fyi (now aliased in Cloudflare). Updates all
references in README, config-help, open-url, and the manual, and
regenerates the concat/man-page artifacts to match.
Function EXAMPLE blocks now render as their own fish fence titled
"Examples" (matching the existing "Usage" title on the Synopsis fence),
triggered by a flat Example: label line mirroring the Synopsis: prefix.
Prose pages get two new generic titling signals in _render_para: a bare
indented path ending in a known extension is titled by its basename, and
a leading "# in <file>" / "# <file>" comment on a shell paragraph is
promoted to the fence title and stripped from the body. This picks up
local.fish/secrets.fish path displays and override examples in
07-customization.md for free, plus a bonus .logging_disabled hit.
10-personalization.md's secrets.fish block gets an explicit "# secrets.fish"
comment to title it the same way. The four local.fish examples keep their
existing descriptive comments rather than a redundant local.fish title.
Swap the Starlight scaffold README for one describing this project's
two-source SSOT and dev/deploy workflow. Give the generated function
synopsis fence a Starlight filename title (`fish title="name.fish"`)
so it reads as a snippet of the function it documents.
Both carry complete headers and are user-facing, but had no # CATEGORY
so generated no entry. Surfaced by the new verify-manual.py warning,
which is exactly what it is there for.
The 8 that still warn are correct exclusions: fast is a self-described
placeholder, the rest are bundled plugin and prompt internals.
Function documentation now comes from functions/*.fish comment headers;
everything else stays in docs/manual/**. Records that split in the three
places a contributor looks:
- AGENTS.md "Documentation Policy" and Coding Convention #4, which now
spells out the full label set and flags CATEGORY as required-to-publish.
- Manual section 11, which pointed readers at docs/manual/ for everything.
- README, same.
The man-page-style comment header above each function in functions/*.fish
becomes the SSOT for that function's documentation. Writing a new function
and documenting it are now the same act.
- manualtools.parse_functions() parses every header carrying a # CATEGORY;
absence of one is the opt-in, keeping bundled-plugin and prompt internals
out of the manual with no exclusion list to maintain.
- build-manual.py generates entries for both --concat and --site, with
**Dependencies:** rendered as links and a **Used by:** reverse index
computed in one pass. Cross-category links are the navigation win.
- docs/manual/05-functions/*.md reduced to frontmatter-only stubs. Every
intro measured zero words, so the category files were pure entry
containers; ordering, titles, and helpKeywords routing are untouched.
- _first_sentence() unwraps the leading hard-wrapped paragraph and skips
the whole Synopsis block, not just its label line. Site cards no longer
truncate mid-clause or show a synopsis as their description.
Verification, per the design spec:
- test_concat_roundtrips_original scoped to sections 0-4 and 6-11. It
guarded a format migration; this is a content migration.
- replaced by structural checks: one entry per categorised function, the
required sections present, every category resolving to a stub with no
stub empty, and every declared dependency resolving to a real function
or a type -q-guarded binary.
- public functions lacking # CATEGORY warn rather than fail, so a new
user-facing function going undocumented stays visible in CI.
24/24 checks pass. 94 entries generated from 94 parsed headers.
Also drops a stale claim from open-url's NOTES: config-help --html calls
xdg-open directly and has never called open-url.
Word-level diff of every manual entry against its generated counterpart
surfaced 546 tokens present in the manual and absent from the header —
losses reconcile.py missed, because it compared description length and
these headers are longer overall thanks to ARGUMENTS/RETURNS.
Merged the substantive ones (546 -> 202 residual tokens, the remainder
being synonym drift). Notable real fixes:
- git-clean: -f/--force was missing from ARGUMENTS entirely
- pkg: per-package-manager query table
- qc: cli-role rationale, role paths, --role passthrough
- config-help: site URL, xdg-open, man page path, case-insensitivity
- agents-init: idempotency, .gitignore paths, upstream pull, wrapper callers
- smart_exit: exit-builtin wiring note, $SCROLLBACK_HISTORY_DIR
The manual's claim that claude/agy pass `agents-init --agents` is stale;
both pass `--quiet` (full setup). Header wins, manual dropped.
Folds the last seven manual entries whose description exceeded their header
back into the source-of-truth comment blocks: config-settings (Sponge/Paths
page detail, list-value parsing, width tiers, navigation keys), fish-deps
(install-method priority, dependency tiers), logs (fzf keybindings, ov
viewer behavior), kitty-logging (symlink wording, C5 inert-vs-uninstalled),
config-update (exec fish reload), yt-dlp (C1 guard). Drops duplicate example
lines left by the previous merge.
Folds the examples Section 5 carried but the headers did not into each
function's `# EXAMPLE`, and moves the three lines that only looked like
examples -- the two typo-abbreviation notes and rm's /usr/bin/rm fallback --
into `# NOTES`, the label already in use.
Also corrects gi's synopsis, which omitted -l, and documents yt-dlp's
--no-embed-thumbnail in `# ARGUMENTS`.
These four were the only documented functions with no comment header,
carrying just a one-line description. Content is merged from their manual
entries plus what the implementations actually do (fc's vi fallback and
empty-buffer abort, sudo-toggle's credential-cache clear), so the headers
are a superset of Section 5 rather than a copy of it.
Records each documented function's manual category in its own header, so
Section 5 can later be generated from source instead of hand-maintained
alongside it. Values reproduce the current grouping in
docs/manual/05-functions/ exactly; no documentation changes meaning here.
Four functions are skipped because they have no header at all yet
(branch, fc, gitup, sudo-toggle); they get one in the merge that follows.
Two-column option and subcommand blocks in the manual were falling through
to the indented-code fallback, rendering as an unhighlighted grey slab on
the site. `_as_table` detects a contiguous, column-aligned indented run and
emits a headerless GFM table instead; anything it cannot prove is tabular
still takes the old path.
15 blocks convert, 20 are correctly left alone. The concat and man-page
outputs are untouched — `prettify` is site-only, and the byte-exact
round-trip test stays green.
Cloudflare Pages reserves a top-level `functions/` directory in the deploy
output for Pages Functions (server-side handlers) and strips it from the
static-asset upload. The wrangler log for run 812 shows the collision
exactly: 159 files uploaded, which is precisely the number of files in
dist/ outside functions/ — all 108 files under it were dropped.
Nothing failed loudly. Astro built all 120 pages, wrangler reported
success, and the site worked under `astro preview`; only the deployed
copy 404'd on every function entry and category index.
Move the generated tree to /reference/ and add a test asserting the site
output never emits a name Pages reserves.
The manual is authored man-page style: every synopsis, example, option
table, and description sits in one 4-space-indented block. On the site
that renders as a single unhighlighted grey slab, because an indented
block declares no language.
Split each block into its paragraphs at site-build time and classify
them: synopsis and shell examples become ```fish fences, descriptions
become real prose, and column-aligned reference tables keep their
indentation. 175 blocks now highlight; the 412 lines of genuine tables
are left alone.
The transform is site-only. docs/manual/** keeps the indented form the
pandoc man-page pipeline and config-help depend on, and a test enforces
that no fence is ever written back to the SSOT.
Also:
- Point Expressive Code at the bundled Catppuccin Mocha/Latte themes so
code blocks match the palette in catppuccin.css.
- Build the functions sidebar group explicitly. `autogenerate` labelled
it with the raw directory slug and republished the directory index as
a child of the group it already titled, producing the duplicate
"Functions Reference" row.
- Skip `Synopsis:` lines when deriving card descriptions; they restated
the calling convention the card already shows as its title.
- Widen the palette: tinted heading levels, inline code, links, card
hover accents, aside accents, and table headers.
Fixes a bug where _split_entries stripped the leading indentation of an
entry's first line, detaching `Synopsis:` from the block it opens.
docs/manual/** plus the Astro Starlight site (https://fish-config-docs.pages.dev/)
replace the Gitea wiki (docs/wiki/) and chunked offline HTML (docs/html/,
docs/html-style.html) as the published documentation surface. Retires the
now-unused docs/split-wiki.py and docs/split-manual.py generators alongside them.
- config-help --html now opens the published site root instead of resolving
a local sitemap anchor; when a keyword was given it prints a note that deep
links aren't available yet and to use the site's search box.
- open-url and docs/manual/05-functions/14-miscellaneous.md examples
repointed from docs/html/index.html to the site URL.
- docs/manual/11-viewing-this-manual.md rewritten to document the four
access paths: the website, the man page, in-terminal pager, and reading
docs/manual/** directly. fish-config.index updated to match the new
headings.
- README.md documentation section and Zoxide attribution link repointed at
the site; corrected the stale "single source file" claim about
fish-config.md.
- Regenerated docs/fish-config.md via build-manual.py --concat.
Adds Node setup, an Astro site build, and a wrangler Pages deploy step
to the existing docs workflow, gated on docs/site/** via the paths
trigger. Also fixes astro.config.mjs's site: URL to match the
fish-config-docs Cloudflare Pages project name (it previously pointed
at fish-config.pages.dev, which is not the project being deployed).
Add build_manual.build_site(), which walks docs/manual and emits the
Astro Starlight content collection: plain pages copied with pipeline-only
frontmatter (man/site/manTitle/helpKeywords) stripped, and *-functions/
category files exploded into one page per function plus a CardGrid/LinkCard
overview. Writes src/sidebar.json for astro.config.mjs to import. Wires
--site alongside the existing --concat flag.
Fixes two latent defects found while building the real site against the
strict content.config.ts schema:
- _split_entries now tracks fenced code blocks (like
manualtools.shift_headings does) so a `## ` inside a fence can't be
mistaken for an entry boundary.
- LinkCard title/description are escaped for JSX attribute context, since
shell synopses routinely contain `<placeholder>` angle brackets that
would otherwise open unterminated MDX/JSX parsing.
Also fixes the generated sidebar shape for the functions category: Starlight
0.39+ dropped support for a bare `autogenerate` sibling of `label` on a
top-level group, so the autogenerate config now nests inside `items`.
Verified with a full `astro build` (temporarily pointing astro.config.mjs
at the generated sidebar.json, then reverted since replacing that config
is a later task's deliverable): 120 pages built cleanly, no
content-collection/frontmatter/MDX errors.
Scaffold docs/site/ via `npm create astro@latest ... --template
starlight`. Extend the docs collection schema in
src/content.config.ts with the four custom frontmatter fields (man,
site, manTitle, helpKeywords) needed by the generator in a later
task, using z.strictObject so unrecognized keys fail the build
instead of being silently stripped by Zod's default behavior.
Ignore generated site output (node_modules, dist, .astro, generated
content, and sidebar.json) in .gitignore.
build-docs.yml ran verify-manual.py before regenerating
docs/fish-config.md, so test_concat_roundtrips_original compared a
fresh concat of docs/manual/** against the stale, pre-push copy on
disk. Any ordinary edit under docs/manual/** — the exact trigger for
this workflow's paths filter — failed the job before it ever
regenerated anything.
Swap the "Generate concatenated markdown" and "Verify manual
integrity" steps so regeneration runs first. Verification still gates
pandoc and the auto-commit step. Also add docs/verify-manual.py to the
paths filter so edits to the integrity checker itself retrigger the
job.
test_concat_roundtrips_original previously compared through
_normalise(), which strips trailing whitespace and drops blank lines.
Mutation testing showed it still passed after joining chunks with a
single newline, deleting all 635 blank lines, and appending trailing
double-spaces to every line. Blank lines are load-bearing for pandoc
(blank_before_header defaults on), so losing them merges paragraphs
and stops headings being headings while the test stays green.
Compare the raw got/want text directly to decide pass/fail. Keep
_normalise only to build the diff shown on failure, normalising both
sides first so whitespace noise doesn't swamp the real difference. If
the exact compare fails but the normalised sides match, say so
explicitly in the assertion message instead of emitting an empty diff.
index.md is both the man-page LANDING section and a Starlight content
page. Astro errors on any frontmatter key outside the fixed
man/site/manTitle/helpKeywords schema, so folding the source
fish-config.md pandoc header (title/section/header/date/author) onto
index.md under a fifth "pandoc" key would break the docs-site build
the moment it's scaffolded.
Relocate that block to docs/manual/_pandoc.yml: a plain, fence-free
YAML file that Astro content collections ignore (leading underscore).
split-manual.py now extracts it as raw text (no yaml.safe_load/
safe_dump round-trip) so build-manual.py's --concat re-emits it
byte-for-byte instead of merely "verbatim" in comment only. Also guard
build_concat against a manual/ tree with no _pandoc.yml/index.md,
removing the unconditional index.md parse that previously raised
FileNotFoundError on such a tree.
Regenerated docs/manual/ via split-manual.py; concat output remains
byte-identical to the pre-migration docs/fish-config.md.
Adds docs/build-manual.py (--concat) and a round-trip test in
verify-manual.py that reproduces the pre-migration fish-config.md
exactly from docs/manual/.
Fixes found by the round-trip check, applied in split-manual.py and
re-run to regenerate docs/manual/:
- NAME/SYNOPSIS/TABLE OF CONTENTS had no sidebar.order, so they sorted
after every numbered section instead of interleaving with DESCRIPTION
in original document order. All manual pages now get sidebar.order
from a single position counter matching source order.
- split_h1/split_h2 used .strip() on section bodies, which also ate
leading indentation on the first body line, corrupting the 4-space
indented code blocks that open SYNOPSIS and TABLE OF CONTENTS.
- The source's leading pandoc metadata block (title/section/header/
date/author) was discarded entirely by the splitter. It's now parsed
off via manualtools.parse and stashed on index.md under a "pandoc"
key; build-manual.py re-emits it verbatim ahead of the first heading.
Replace .lstrip('\n') with .removeprefix("\n") to preserve body text that
legitimately starts with blank lines. The serialize() function inserts exactly
one separator newline; removing only that one newline (via removeprefix) rather
than all leading newlines (via lstrip) maintains parse/serialize roundtrip
losslessness.
Adds regression test to verify bodies with leading blank lines roundtrip
correctly.
Relocate the Kitty scrollback watcher out of the single-purpose kitty/
directory into scripts/kitty-fish-config-watcher.py, and change the
installer to symlink it into the Kitty config directory instead of
copying it.
The symlink always tracks the canonical source, which removes the
version-staleness comparison and the copy-vs-refresh messaging. uninstall
now removes a symlink (including a dangling one) or a legacy copied file.
Existing installs migrate automatically on the next `kitty-logging install`.
Docs (README, docs/fish-config.md, wiki) updated to match.
Defaults to the bundled 'cli' role (concise, terminal-friendly output),
installed on first use by symlinking scripts/cli-agent.md into the aichat
config dir. Inherits all aichat flags and completions via --wraps; passing
--role/-r forwards unchanged. Only defined when aichat is installed.
--help prepends a banner and rewrites aichat's own help to qc.
Docs: fish-config.md 5.12 + index keywords.
Extract the user-dots symlink logic into the __fish_user_dots_link helper and
add a dedicated __fish_user_dots_symlink toggle, surfaced as a 'Dots link' bool
row on the config-settings Paths page. Unlike the opinionated categories it has
no universal/session split — it acts on a literal path.
Setting it falsy (or toggling off) stops symlink generation and removes any
existing link immediately, honoured regardless of the C2 master switch.
Creation remains a C2 startup side-effect. config.fish now calls the helper.
Docs: README, fish-config.md (C2 table, Paths page, machine-local section),
and fish-config.index updated.
Point $__fish_config_dir/user-dots at $__fish_user_dots_path on interactive
startup so the private overlay can be browsed from the fish config dir. The
link is created if missing and repointed if the path variable changes, only
ever managing a symlink (never clobbering a real file/dir). Gated as a C2
startup side-effect (__fish_config_op_autoexec) and git-ignored.
Docs: README overlay section and fish-config.md C2 table updated.
Fish 4.x ships the native `help` function embedded in the binary
(embedded:functions/help.fish) with no on-disk file. The old
functions/help.fish tried to `source $__fish_data_dir/functions/help.fish`
to back up the native help before shadowing it — that path no longer exists,
so the first `help config ...` call errored:
source: No such file or directory
functions: Function 'help' does not exist
The backup cannot happen from functions/help.fish at all: an autoload shadow
of that name makes `help` resolve to our own wrapper (or nothing, mid-load),
so `functions -c help` can never capture the embedded original.
Move the wrapper to conf.d/help.fish, sourced at startup before any shadow
exists, where `functions -c help __original_help` copies the embedded native
help. Behavior is otherwise unchanged: 'help config' delegates to config-help,
all other topics fall through to __original_help, and the C1 opinionated guard
still applies. Delete the obsolete functions/help.fish.
Extract the browser-detection and launch logic out of config-help into a
reusable open-url function, then build repo-open on top of it to open the
current repo's origin remote in a browser.
- open-url: resolve the best graphical browser (fish_help_browser -> BROWSER
-> xdg-mime https handler -> known binaries -> xdg-open) and launch it
backgrounded. Silent by default; -v/--verbose reports the browser, -s/--silent
is accepted explicitly. Browser console chatter is discarded.
- repo-open: normalize the origin URL from HTTPS and SSH/scp forms, deep-link
to the current branch (falling back to the remote default) and sub-directory.
Provider layout resolved via git config browse.provider, hostname heuristic
(github/gitlab/gitea/bitbucket, codeberg->gitea), then github default.
-p/--print emits the URL, -r/--root ignores the sub-directory.
- config-help: replace the inlined browser block with an open-url call.
- abbr: add open-repo and url-open abbreviations that expand to the canonical
command names on space/enter.
- docs: document both functions in the SSoT (fish-config.md + index) and add a
repo-open row to the README doc-browsing table.
Previously list rows (Extra secret, OK codes) split on spaces only, so
'KOPIA, TEST' produced the malformed token 'KOPIA,'. Collapse any run of
commas/whitespace to a single space before splitting, so 'A,B', 'A, B' and
'A B' all yield the same entries.
Replace the fish `read` prompt (which showed an unstyled `read>` and left the
prompt line behind on redraw) with an in-place editor built on the raw key
reader. The value is edited directly in its UI field with a block caret; the
panel redraws each keystroke and cleans up on exit. Pre-fills the current value;
Backspace deletes, Enter saves (empty reverts to default), Esc cancels.
- __config_settings_read_key: decode Backspace (bytes 8/127)
- __config_settings_draw_value: edit-mode field with caret + edit hint line
- config-settings: inline edit loop replaces the read-based prompt block
A blank or escaped inline edit, and the ← clear, previously erased the variable.
sponge reads sponge_delay / sponge_purge_only_on_exit / sponge_allow_previously_
successful with no fallback, so an unset value crashed the prompt
('test: Missing argument'). Fixes:
- Value rows reset to a per-row default value (sponge_delay→2, exit_codes→0) or
erase only when the var tolerates unset (paths, extra-sensitive list).
- Blank/escaped Enter reverts to that default instead of writing empty.
- Sponge booleans are now a 2-state true/false (sponge's convention), never unset.
- Defensive set -q;or set -l fallbacks added to the sponge consumer functions so
a transiently-unset var can never error the prompt.
- C1: sponge_purge_only_on_exit / sponge_allow_previously_successful are 'bool'
rows that write true/false (sponge's convention), not on/off; badge maps
true->ON, false->OFF, unset->DEFAULT
- I1: shorten value-page hint to 49 cols so it fits the 50-wide tier
- M1: set -U -- before the var name guards typed values beginning with a dash
- §1 Scrollback History: __fish_scrollback_history_* source-of-truth + exported
mirror, and the no-global-shadow rationale
- §Sponge History Filtering: __fish_sponge_extra_sensitive name tokens (--entire
match) and the tuning vars surfaced on the Sponge page
- config-settings function reference: four-page model, Tab/Shift-Tab, value rows
- index + README updated
A global __fish_scrollback_history_dir/_max_files would shadow the universal
that config-settings writes, defeating live mirror updates and stale-displaying
the value until restart. Export the default, override from the universal only
if set.
Both the auto-pull function and the PWD event handler hardcoded
$XDG_CONFIG_HOME/.user-dots/fish as the registry directory. They now
resolve $__fish_user_dots_path first, falling back to the same default,
so a custom path set via config-settings is honoured.
- Add __fish_user_dots_path as 8th entry in vars list
- Update panel_h from 14 to 16 (matches draw function's 16-line output)
- Clamp cur_row down to min(7, ...) to allow navigation to path row
- Add did_redraw flag (reset per iteration) to skip double-redraw after Enter
- Add Enter handler for row 7: erases panel, prompts for path, sets or clears
__fish_user_dots_path universally, redraws, sets did_redraw
- Special-case RIGHT on row 7 as no-op (path is set via Enter only)
- Special-case LEFT on row 7 to clear path var via apply DEFAULT
- Add Enter key hint to --help navigation section
- Fix EXAMPLE block in __config_settings_draw docstring to include 8th arg
Allow users to customize the location of their private overlay directory
via `set -U __fish_user_dots_path /your/path`. Falls back to the previous
hardcoded default of `$XDG_CONFIG_HOME/.user-dots/fish` when unset.
Simplify the sourcing model: config.fish now sources only local.fish,
which is responsible for sourcing its own secrets.fish companion. The
redundant direct sourcing of secrets.fish from config.fish is removed.
Update docs/fish-config.md (Sections 1, 7, 10) and README.md to
document the new variable, the custom-path override pattern, and the
simplified sourcing model.
The generated PTY-logging wrappers hardcoded /usr/bin/{paru,yay} both for
the presence check and as the command the wrapper shells out to, breaking
on any host where the binary lives elsewhere. Resolve the real path via
__fish_real_command (which skips our own shim) and embed that. Bump the
wrapper version 5 -> 6 so existing installs regenerate.
Add __fish_real_command, which walks all PATH matches for a name and
returns the first that is NOT one of this config's generated wrappers
(identified by the "# <name>-wrapper-version:" marker; grep -I treats
real ELF binaries as no-match so only our text shims are skipped). It
never returns one of our own wrappers, so a caller embedding the result
can't build a shim that recurses into itself.
Use it for the fish-deps status "(Found at ...)" path so paru/yay show
the real binary instead of the ~/.local/bin logging shim.
Status, install, and update resolved catalog entries with `type -q`,
which also matches wrapper functions that shadow a tool name (rg, rm,
yt-dlp). A shadowed-but-uninstalled tool was reported "installed",
skipped by `install`, and skipped by `update`. Switch these catalog-bin
probes to `command -q`/`command -s` (PATH only). PM/build-tool probes
(cargo, uv, paru, yay, ...) and the fisher check (a fish function) keep
`type -q`.
Add functions/yt-dlp.fish, shadowing yt-dlp to prepend sane defaults
(--sponsorblock-remove all, --embed-subs, --embed-metadata,
--embed-thumbnail). Each default is suppressed when the user already
passes that flag, its alias (--add-metadata), its negation
(--no-embed-thumbnail), the --opt=value form (--sponsorblock-remove=...),
or the global --no-sponsorblock kill. User args pass through last so an
explicit flag wins on precedence. Gated as a C1 opinionated alias;
falls back to bare `command yt-dlp` when disabled.
Register yt-dlp as a recommended (rec tier) dependency in the fish-deps
catalog and document the function (§5.13) and dependency in the SSOT
and index.
Add the auto-pull function entry (5.4 Git) and index entry, a C2 component
reference row plus explanatory paragraph in fish-config.md, and update the
README C2 disable-list. (AGENTS.md C2 table, file tree, and task #12 are
tracked in the git-ignored AGENTS/ dir.)
Add a C2-guarded PWD handler that background fast-forwards the fish-config
repo (baseline) plus any repos in a machine-local registry. Safety is
guaranteed by _auto_pull_sync: clean tree + has-upstream + --ff-only, else
no-op. Never rebases, merges, or overwrites work.
- conf.d/auto-pull.fish: --on-variable PWD handler, throttled to fire once
per repo entry; spawns a --no-config child to run the worker
- functions/_auto_pull_sync.fish: the ff-only worker (safe on any branch)
- functions/auto-pull.fish: add/remove/list/status registry management,
usable even when C2 is disabled
- completions/auto-pull.fish: subcommand + registered-repo completions
Registry lives at ~/.config/.user-dots/fish/auto-pull.list (machine-local,
never committed).
VISUAL was hardwired to $EDITOR (nvim), so 'edit --visual' would launch a
terminal editor detached with no tty. Comment it out so --visual falls
through to the GUI fallback chain, and let users set a real GUI editor via
local.fish. Update the editor-variable docs to match.
The local core.hooksPath override set by agents-init shadowed the user's
global hooks (ggshield, Git LFS) since git honors only one hooksPath. Each
shim now execs the global/system hook of the same name after running
version-bump, so global hooks still run after version increment. Bumped the
agents-tools version marker to 2 so existing AGENTS repos refresh.
A file whose first lines contain a bare '---' (e.g. YAML frontmatter)
caused 'string match -qr' to parse the line as an option flag, raising
'string match: ---: unknown option'. Add '--' to end option parsing.
Drop the save-session/resume system entirely:
- functions/save_claude_session.fish, save_antigravity_session.fish
(session-start hook scripts)
- functions/claude-resume.fish, antigravity-resume.fish, code-resume.fish
(consumers of the .claude_session/.antigravity_session files)
Also updates docs/fish-config.md (removes the three function sections,
drops the session-helper mention from the python3 dependency note) and
docs/fish-config.index (removes the orphaned keyword entries). Generated
html/wiki/man are rebuilt by build-docs.yml on merge.
External hook registrations were removed from ~/.claude/settings.json and
~/.gemini/settings.json (the latter pointed at an already-deleted
save_gemini_session.fish); those files live outside this repo.
The zellij wrapper (functions/zellij.fish) rewrote every `zellij`
invocation as `zellij options --theme catppuccin-mocha <args>`, which is
only valid for launching a new session. This mangled every subcommand,
including the `zellij action dump-screen` call inside _zellij_dump_log,
so no logs were ever produced. The theme is already set in config.kdl,
making the wrapper redundant — remove it.
Also harden _zellij_dump_log:
- dump-screen takes the file via stdout redirect, not a positional arg
(rejected by zellij 0.44) nor --path (server-side write, flaky)
- add --ansi to preserve color in the logs
- discard empty dumps instead of leaving junk files
Document the structural limitation: zellij can only snapshot on a clean
shell exit, unlike tmux's continuous pipe-pane stream. Closing a pane or
quitting zellij tears down the pane/server before it can be dumped.
- abort install if the watcher copy fails (was wiring a block pointing at
a missing file and reporting success)
- handle dismiss before the kitty guard so it works without kitty installed
- require both managed-block markers before the uninstall range-delete to
prevent deleting to EOF on a malformed block
Add a Session Logging section and a CAUTION callout to the README, and a
matching privacy notice to docs/fish-config.md, making clear that this
config logs terminal sessions (Kitty/tmux/zellij/paru/yay) to
~/.terminal_history by default. Point users at both the
__fish_config_op_logging variable and the interactive config-toggle TUI
for opting out.
Zellij has no live-stream facility like tmux pipe-pane, so capture is a
one-shot 'zellij action dump-screen --full' run from a fish_exit handler
(conf.d/zellij-logging.fish -> functions/_zellij_dump_log.fish). The C5
guard is checked inside the helper at exit time, so toggling logging
needs no sync_logging coordination — there is no persistent stream.
Extract pruning into functions/_prune_terminal_logs.fish, shared by both
the tmux and zellij helpers. This also fixes a latent bug in the tmux
helper: globbing tmux_*.log directly errored with 'No matches for
wildcard' on the first log in an empty dir. The shared helper globs via
'set' (tolerates no-match) and uses command ls/rm to bypass the eza and
trash C1 shadows.
Extract the tmux pipe-pane setup into functions/_tmux_pipe_log.fish,
called by both conf.d/tmux-logging.fish (startup) and
__fish_config_sync_logging (C5 re-enable). The helper prunes the oldest
tmux_*.log files by mtime to stay within SCROLLBACK_HISTORY_MAX_FILES,
matching the paru/yay wrappers.
Uses 'command ls' to bypass the eza ls shadow, which injects OSC-8
hyperlink escapes into paths and corrupted the filenames passed to rm.
Starts tmux pipe-pane capture for the current pane whenever fish
launches inside a tmux session. Each shell gets a timestamped log
in SCROLLBACK_HISTORY_DIR. Toggling __fish_config_op_logging stops
or restarts the pipe in all open fish shells via the existing
--on-variable event handlers.
- quiet mode now outputs one summary line only when something actually changed;
idempotent re-runs produce no output
- add -v/--verbose flag as an explicit alias for the default verbose behavior
- gitignore helper output captured to detect changes without printing in quiet mode
- drop eager "Initializing…" header in favour of end-of-run conditional summary
- Strip leading / from pattern before git check-ignore so root-anchored
patterns like /AGENTS.md are checked as repo-relative paths (AGENTS.md)
and correctly match existing rules — fixes duplicates on every run
- Rework helper to accept multiple patterns and write them as a single
labeled block with project-style header/footer comment rather than
appending bare patterns one at a time
- Move gitignore calls out of per-plug loop in --plugins mode so all
three docs/ patterns are checked and written in one block
- Remove 5 duplicate bare entries left in .gitignore by the broken runs
- Move plugin dir creation into --plugins mode (not 'Always') so --agents
alone no longer creates empty AGENTS/plugins/ dirs
- Wrappers (claude, agy) now call plain agents-init (both modes) so plugin
dirs in docs/ are migrated on the first AI launch, not just --agents
- Rewrite --agents CLAUDE.md logic: detect which root files are real vs
symlinks and handle all four cases (both/agents-only/claude-only/neither)
without ever losing content
- AGENTS/CLAUDE.md is now its own file in AGENTS/ (real file when both
existed, symlink → AGENTS.md for single-source cases)
- Root CLAUDE.md now points to AGENTS/CLAUDE.md instead of AGENTS/AGENTS.md;
readlink checks auto-fix existing symlinks with the wrong target
- New empty setups get AGENTS/AGENTS.md pre-populated with the agent
directive warning editors not to write through the root symlinks
Startup side-effects that modify the filesystem belong in first-run, not
in a recurring conf.d fragment. The symlink is now created once (like a
real install step) instead of being checked on every shell launch.
MANPATH addition stays in tricks.fish — that's an env var that must be
set each session.
Panel now selects from four width tiers based on $COLUMNS (with a 6-col
buffer per side before stepping up): 52-wide (default), 70, 74, or 78.
Each tier carries richer category descriptions sized to fit the layout.
The box is horizontally centered on every draw via a left-padding prefix.
Key reader switches from stty min 1 to min 0 / time 3, giving a 0.3 s
poll interval so COLUMNS changes are detected without a keypress. The
erase formula is now wrap-aware: prev_max_line_width / COLUMNS gives the
wrap factor, ensuring old wider panels are fully cleared after narrowing.
Idle timeout ticks that detect no resize are skipped entirely.
New functions/claude.fish wraps the claude CLI. Before launch it checks the
current directory and the git project root; when CLAUDE.md is absent but
AGENTS.md is present, it creates a relative symlink CLAUDE.md -> AGENTS.md so
Claude Code picks up shared agent instructions without duplicating the file.
Arguments are forwarded verbatim.
Implemented as a C1 command shadow: when __fish_config_op_aliases (or the
master __fish_config_opinionated) is disabled, the call passes through to the
bare claude binary unchanged. Link-creation notices print to stderr in green.
Documents the new shadow in docs/fish-config.md (section 5.12 AI tools, C1
component reference table, and C1 summary list) and adds a claude-cli anchor
to docs/fish-config.index.
When a category variable is set explicitly in both universal and session
scope, interactive fish prints a one-line stderr warning ("successfully set
universal 'X'; but a global by that name shadows it") on each `set -U`/`set
-g`. That stray line landed between the apply and the in-place panel redraw,
pushing the cursor down one row so the `\e[14A` cursor-up no longer reached
the top border — leaving it behind to stack on every toggle and persist
after exit.
Suppress stderr on the six set commands in __config_toggle_apply. The
warning is expected noise here since config-toggle edits both scopes
independently. The warning only fires in a real interactive TTY (not under
`fish -ic`), which is why it was easy to miss when testing.
Required tier is now fish, fzf, and zoxide only — the tools the config
meaningfully can't function without. Everything else degrades gracefully.
- cargo: only used by fish-deps to install Rust tools or build fish from
source; all paths are already gated on type -q cargo
- starship: type -q guard in conf.d/starship.fish; shell falls back to
fish's built-in prompt without it
- fisher: auto-bootstrapped by first_run.fish; no need for users or
fish-deps to manage it. Remove from catalog and clean up the now-dead
fisher-bootstrap/special-fisher installer cases.
Catalog arrays verified aligned at 26 entries each.
direnv integration is fully guarded with type -q direnv in config.fish.
The auto-venv script checks $DIRENV_DIR (set at runtime), not the binary.
Without direnv installed the hook simply never loads and venv activation
fires normally. No functionality breaks.
paru and yay were already classified as rec in _fish_deps_catalog.fish
(they've always been position 9-10 in the tiers array with rec values)
but docs/fish-config.md still listed them under Required. Non-Arch
systems have had silent guards throughout, so they were never truly
required. This syncs the docs with what the catalog already says.
uv is only used in the fish-deps fish-from-source build path
(uv run --no-managed-python cargo install --path .) and is not required
by the config at runtime. All consumers degrade gracefully without it.
pipx appeared in the installer's method-building and execution switch
blocks but no catalog entry ever sets special=pipx, making both branches
permanently unreachable dead code. The docs listed pipx as install
priority #6 which was equally misleading.
- _fish_deps_catalog: change uv tier from req → rec
- _fish_deps_install: remove case pipx method-builder and
special-pipx / special-pip execution cases
- docs/fish-config.md: move uv from Required to Recommended catalog
entry with accurate description; drop pipx from install priority
list and tier summary
python3 is used unguarded by the AI session helpers and (guarded) by the
paru/yay log cleaner, but was absent from the dependency catalog and docs.
uv does not provide python3 on PATH, and Arch's base omits it, so it is
tracked separately rather than assumed via uv.
- Add python3 (recommended tier, pm: python) to _fish_deps_catalog.fish
- Guard python3 calls in save_claude_session/save_antigravity_session with
`type -q python3`, emitting valid empty JSON when absent (Convention §6)
- Document python3 in docs/fish-config.md (§5.6 tiers + catalog entry)
pacman/paru download progress is a multi-line terminal animation: it
repaints lines in place using ANSI cursor-movement (ESC[<n>A) and
erase-line (ESC[K) sequences, not just carriage returns. The previous
line-wise regex approaches could not reconstruct this — frames either
concatenated into one giant line (CR removed) or collapsed to blanks
(CR kept), discarding the final 100% frame.
Add scripts/clean_progress_log.py, a small dependency-free terminal
screen-buffer emulator that replays the cursor movements against an
in-memory grid and dumps the final static frame, preserving SGR color
so logs still render with color in ov/bat/less -R. It also drops the
script(1) header/footer.
Both wrappers now pipe the raw PTY capture through this cleaner (bumped
to version 5), falling back to stripping only the script(1) header when
python3 is unavailable. Document the scripts/ dir and mechanism in
AGENTS.md and docs/fish-config.md.
col -bp is designed for backspace-overstriking (man pages), not ANSI
terminal animations; it mangled escape sequences and garbled overprinted
progress bar text. Replace with a perl -ne one-liner that:
1. Skips Script started/done header lines (next if matches, with -ne
so next truly suppresses print, unlike -pe which still auto-prints)
2. Strips trailing \r from PTY \r\n line endings
3. Collapses CR-redrawn progress bar frames to their final state
4. Preserves all ANSI color codes so ov renders them correctly
Bump wrapper version to 4 to force regeneration.
script(1) captures every \r-redrawn frame of the pacman progress bar
as raw bytes. The previous sed pass only stripped ANSI codes, leaving
all intermediate frames concatenated in the log. col -bp semantically
replays the carriage-return overwrites and retains only the final state
of each line; the sed pass then strips residual ANSI codes and the
"Script started/done" header that script(1) writes to the file even
under -q. Bump wrapper version to 3.
Piping through tee caused libalpm to detect a non-TTY stdout and
suppress download progress bars. Switch to script(1) with -q -e -c
which allocates a pseudo-TTY so paru/yay see a real terminal, then
strip ANSI escape sequences from the captured log for readability.
Bump wrapper version to 2 to force regeneration on next shell start.
Promote config-toggle to a callout at the top of the Minimal Mode
section so users see the interactive UI before the variable table,
and drop the now-redundant tip at the bottom.
Add docs/plans, docs/specs, docs/superpowers, and .superpowers to
.gitignore and stop tracking the two config-toggle artifacts that were
committed before the ignore rules existed. The files are kept on disk
(now ignored), only removed from version control.
The badge now positions each state by where it sits on the scale: OFF
left-aligned, DEFAULT centered, ON right-aligned. This makes the
OFF ← DEFAULT → ON ordering visible at a glance and reinforces the
direction the ←→/h l keys move.
Directional arrows fully cover value changes, so the Space cycle is
removed. Add h/l as vim-style aliases for ←/→ (matching the existing
j/k for up/down), keeping the whole keymap hjkl-consistent. Update the
in-panel hint, help text, docstrings, and offline docs accordingly.
Left/Right now adjust the highlighted value one step along the
OFF ← DEFAULT → ON scale, clamped at the ends (no wrap), complementing
Space which cycles through all states and wraps. Right steps toward ON,
Left toward OFF.
Extract the set/erase side-effect into __config_toggle_apply so Space,
Left, and Right share one implementation of the scope-aware
set -U/-g/-Ue/-eg logic. Update the in-panel keybind hint (now
width-padded via string pad so the border stays aligned) and the help
text and offline docs to cover the new keys.
fish's `read` invokes its interactive line editor on a TTY, which (1)
prints a `read> ` prompt below the panel, (2) intercepts Tab and arrow
keys for its own line editing so they never reach the switch, and (3)
shifts the cursor down a line, throwing off the `\e[14A` redraw so top
borders stacked on every keypress. Plain keys (j/k/q/space) passed
through, masking the problem.
Add __config_toggle_read_key: puts the terminal in raw, no-echo mode
(`stty raw -echo min 1 time 1`), reads one keypress from /dev/tty, and
returns a normalized token (up/down/left/right/tab/space/escape/quit or
the literal char) by decoding the bytes via od. Arrow keys and Tab now
work, there is no stray prompt, and the redraw stays aligned. Ctrl-C in
raw mode arrives as byte 3 and maps to quit; bare Esc exits after the
0.1s inter-byte timer.
Rewrite the event loop to consume these tokens and restore Esc to the
help text.
The event loop used `read -k 1`, but `-k` is not a valid fish read option
(it errors with "unknown option", status 2). read therefore returned
instantly every iteration without consuming a keypress, so the loop
redrew the panel as fast as the terminal could render and ignored all
input. The nchars flag is `-n`, not `-k`.
Switch to `read -s -n 1` (one char, silent so keystrokes don't garble the
panel) and add `or break` so a read failure (EOF / non-tty stdin) exits
cleanly instead of spinning. Applies to the primary read and both escape
sequence continuation reads.
fish's read -k N waits for exactly N bytes; single-char keys ('q', 'j',
Space, Tab) were blocking indefinitely waiting for 2 more bytes, causing
the input loop to appear unresponsive. Random 3-key bundles were then
processed as unrecognised input, triggering infinite redraws.
Switch to read -k 1 (one raw byte per call). Arrow keys still work: the
terminal sends ESC+[+A/B as a burst, so after reading ESC the two
continuation bytes are already in the TTY buffer and the follow-up reads
return immediately. Bare ESC now passes the next keypress through as the
effective key rather than exiting (q/Q remain the exit keys).
Replace two-read-k-1 ESC handling with a single read -k 3 so that a bare
ESC returns immediately instead of blocking the shell indefinitely waiting
for a second byte. Add trap - INT in the cleanup block so the signal
handler does not leak into the global session after config-toggle exits.
Interactive TUI for toggling opinionated component categories and master
variable. Tabbed Universal/Session scope, arrow-key navigation, Space to
cycle ON/OFF/DEFAULT with immediate apply.
Promotes the internal opinionated_catalog.md (git-ignored dev reference)
to first-class user documentation in docs/fish-config.md Section 7.
- Add per-category component tables (C1–C6) under a new "Component
Reference" subsection in "Opinionated Components (Minimal Mode)"
- Document the C5 sentinel-file coordination mechanism and how
__fish_config_logging_changed propagates changes to all open shells
- Document C3/C5 composition (smart_exit wrapper vs capture block)
- Document bang-bang system atomicity across its multiple source files
- Add rg function entry to Section 5.1 (Kitty hyperlink wrapper)
- Update fish-config.index with keywords for all new headings
When smart_exit skips fish-side capture due to the C5 guard, it now sets
logged_by_shell=true on the Kitty window before calling builtin exit. This
prevents watcher.py's on_close handler from capturing the scrollback even
if the sentinel file is absent, providing a second layer of protection.
Also restructures the capture block to be flat (no wrapper if-true) after
the early-exit guard.
--on-variable handlers in functions/ are only autoloaded on explicit call,
so they never fire when a universal variable changes. Moving the definitions
to conf.d/logging-events.fish ensures they are registered at shell init.
Also adds a startup __fish_config_sync_logging call so pre-set variable
values (e.g. set before this shell was opened) take effect immediately
without requiring a re-set.
Add __fish_config_op_logging (C5 — Logging & Capture) to the opinionated
components variable table and update the master-disable example comment
from "four categories" to "five categories".
AGENTS.md and opinionated_catalog.md are git-ignored per project policy;
those files were updated on disk but cannot be tracked in this repo.
Add C5 (Logging & Capture) guard to wrapper generation in both
conf.d/paru-wrapper.fish and conf.d/yay-wrapper.fish. When C5 logging
is disabled, the guard removes any generated wrapper and returns early,
allowing the system to fall back to the bare binary.
Also replaces stale Task #4 comment references with C5 classification.
Adds 'Opinionated Components (Minimal Mode)' to docs/fish-config.md
with index keywords (opinionated, minimal, minimal-mode, opt-out,
toggles) and a Minimal Mode section with toggle table to README.md.
AGENTS.md Task #3 checklist ticked locally (file is git-ignored).
C1 shadows (rm, cat, ls, less, du, bash, top, ping, ssh, rg, mkdir,
help) fall back to the bare command when __fish_config_op_aliases is
falsy; rm falls back to exact 'command rm' with no wrapper. C2 gates
the auto-venv PWD hook. C3 gates smart_exit (composing with Task #4
logging), fish_right_prompt, and all six expand_bang_*/expand_typo_sub
functions atomically with the bang-bang system. C4 integration commands
(spwin, tab, split, hist, logs, upgrade) refuse with a colored stderr
error when disabled. config.fish now also strips the CachyOS distro
config's own bang-bang bindings, history override, and alias opinions
per category, restoring fish stock functions where they exist.
- Section keyword is now extracted early and shared across all three
output modes (pager, HTML, man) rather than duplicated per branch
- --html with a section keyword resolves the heading to a pandoc anchor
ID and looks it up in docs/html/sitemap.json; handles both sub-section
fragment paths and top-level sections that are their own page
- --man with a section keyword overrides MANPAGER to `less +/pattern`
so the page opens at the nearest heading match
- --help output updated to show [section] in USAGE and section+flag
examples (help config keybindings --html, help config pkg --man)
- docs/fish-config.md §5.14 synopsis, flags, and examples updated
- docs/fish-config.md §11 "Viewing" sections updated for both HTML and
man page to document the section+flag invocation
- README table updated with section+html and section+man rows
- help.fish: expand SYNOPSIS/DESCRIPTION to document -w/--html, -m/--man,
-h/--help flags; note flags are only intercepted when 'config' is argv[1]
- config-help.fish: add # NOTES section explaining help config as the
preferred invocation; update --help banner to show both names; update
--help USAGE/EXAMPLES output to use `help config` syntax throughout
- docs/fish-config.md: update §5.14 synopsis/examples and "Viewing" sections
to use `help config` as primary form; inline note for direct config-help use
- README.md: update docs table to show `help config --html` / `--man`
conf.d/sponge_privacy.fish registers patterns and filters that prevent
credentials from reaching fish history:
Layer 1 (static regex, universal): auth flags, env assignments,
credential-bearing URLs, Authorization headers, sshpass, docker
login, openssl -passin/-passout
Layer 2 (dynamic values, session globals): on the first prompt, after
secrets.fish has loaded, reads the literal values of all exported
credential-named vars (TOKEN, PASSWORD, SECRET, etc.), escapes them
for regex, and merges them with the static patterns as a session
global — auto-refreshes on login so rotated tokens are never stale
Layer 3 (per-command filter, sponge_filter_secrets): catches
credentials in variables exported mid-session (e.g. project .env)
Also exempts functions/sponge_filter_secrets.fish from the sponge_*
gitignore glob so our custom filter is committed alongside the config.
meaningful-ooo/sponge is now the one true Fisher-managed plugin,
giving the bootstrap a concrete purpose. Its files (and functions/fisher.fish,
completions/fisher.fish) are gitignored so Fisher owns them exclusively —
no committed/managed conflict possible.
Updates docs, index, requirements, and README to distinguish
Fisher-managed plugins from bundled customized ones.
Only jorgebucaran/fisher itself is in fish_plugins. The functionality
from catppuccin/fish, fzf.fish, done, autopair, and puffer-fish is
bundled directly with this config in modified form and must not be
installed or updated via fisher.
Removes sponge (not present), corrects file path mappings for bundled
components, fixes stale "Plugin sync failed" message in first_run.fish,
and expands fish-config.index with missing sections 9–11.
Reorder sections so Installation (§9) and Personalization (§10) precede
Viewing This Manual (§11). Update TABLE OF CONTENTS and regenerate wiki;
old 9-viewing-this-manual.md replaced by 11-viewing-this-manual.md.
- docs/fish-config.md: add §10 Installation (clone, sentinel guard,
config-update usage) and §11 Personalization (secrets.fish /
local.fish examples); update TABLE OF CONTENTS
- docs/split-wiki.py: strip trailing thematic break from DESCRIPTION
body so index.md no longer renders a double --- separator
- Regenerate docs/wiki/ with 11-installation.md and
12-personalization.md; all nav bars updated
- 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
Adds docs/split-wiki.py, a Python script that splits fish-config.md
into a multi-page Markdown wiki under docs/wiki/:
- index.md: DESCRIPTION intro + full section ToC
- one file per numbered section (1-configuration-variables.md … 9-viewing-this-manual.md)
- each section page has a nav bar at the top linking to every other section
The build-docs.yml workflow now runs the script alongside pandoc so all
three formats (man page, HTML, wiki) are regenerated together from a
single source in one CI run.
README slimmed down to a pointer to the wiki; docs/fish-config.md §9
gains an "As a wiki" subsection.
Both workflows triggered on the same path change, installed pandoc
separately, and raced to commit — the second always failed on push
due to new commits from the first. A single job installs pandoc once,
generates both outputs, and commits them together.
config-help gains two new flags:
- --html / -w: opens docs/html/index.html in the default browser using
smart browser detection (xdg-mime https scheme handler → known binaries
→ xdg-open fallback) to avoid MIME-type mismatches with non-browser apps
- --man / -m: opens the compiled docs/fish-config.1 man page via man -l
config-update is a new function that pulls the latest fish config from the
hard-coded upstream URL without requiring a configured git remote. Suppresses
git output and reports status with colored messages. Supports --dry-run and
--force flags.
README updated to document all new commands.
- Add docs/html-style.html with Catppuccin Latte/Mocha palette,
auto-selected via prefers-color-scheme
- Update html-docs workflow: embed stylesheet via --include-in-header,
remove --toc so per-page sidebar is gone (index.html remains the ToC)
- Touch docs/fish-config.md to trigger the HTML generation workflow
fix(ci): clear docs/html/ before pandoc to avoid directory-exists error
fix(docs): restore toc on index, hide it on section pages via JS, fix
full-page bg
fix(docs): fix nav alignment by grouping label+link pairs as flex units
chore(docs): regenerate offline HTML docs
The `actions/gitea-issue-create@v1` action does not exist on GitHub,
causing the docs-drift workflow to fail at clone time. Replace it with
a direct call to the Gitea REST API using curl. Also corrects the label
from `documentation` to `Kind/Documentation`.
Rename config_help → config-help and add a help wrapper that
intercepts 'help config [section]', forwarding sub-topics to
config-help. Update README and docs to use 'help config' as the
preferred interface so offline docs feel like a natural extension
of fish's built-in help system.
The symlink from ~/.local/share/man/man1/fish-config.1 to
docs/fish-config.1 is now created automatically alongside the
existing MANPATH setup, making `man fish-config` work out of the
box on any machine after cloning. Simplified docs accordingly.
Adds man page viewing instructions to README Offline Documentation
section and to docs/fish-config.md section 9, including a note that
fish-config (hyphen) is this config's man page while fish_config
(underscore) is fish's built-in browser tool.
Section headers in bold blue, argument/flag names in yellow, command
examples in green, navigation keys in cyan, fallback chain numbers
dimmed. All reset to normal after each colored span.
- config_help --help / -h prints full usage, section keyword examples,
ov navigation key reference, and the pager fallback chain.
- Prepend a dim nav hint line to the ov input stream and pin it with
--header 1 so "Space=next section ^=prev Alt+u=sections /=search
q=quit" is always visible at the top of the screen.
- Add docs/fish-config.index mapping 100+ keyword aliases to exact heading
text; config_help looks up here first, falls back to normalized heading
scan (strips non-alphanumeric, lowercases both sides) for unknown terms.
- Resolve line numbers at runtime with grep -F so the index never goes
stale from doc edits — only heading renames require an update.
- Fix section jump: --section-header pins delimiter lines as sticky headers
removing them from ov pattern-search scope. Replace --pattern with
tail -n +$start_line piped before ov; the target section is the first
line so no search is needed and forward section nav still works.
- Fix empty sections sidebar: ov matches --section-delimiter against
logical (ANSI-stripped) text, so "^#" is correct for bat-colored output;
the previous ANSI escape-sequence regex never matched anything.
- docs/fish-config.md: curated terminal-optimized manual covering all
public functions, keybindings, abbreviations, configuration variables,
dependency catalog, and customization guide. Written for ov/bat/less
readability rather than browser rendering — no callouts, no hyperlinks.
Pandoc-compatible YAML front matter for man page compilation.
- functions/config_help.fish: viewer function with fallback chain
ov -> bat -> man -l -> less -> cat. Accepts an optional section
keyword to jump directly to the first matching heading.
- .gitea/workflows/man-page.yml: compiles docs/fish-config.md to
docs/fish-config.1 via pandoc on every push to main that touches the
source doc, then commits the result automatically.
- .gitea/workflows/docs-drift.yml: opens a reminder issue whenever
README.md changes without a corresponding docs/fish-config.md update
in the same push.
- README.md: documents config_help and the offline manual.
- AGENTS.md: adds Convention 10 requiring offline doc to be updated
alongside any function, keybinding, or config change.
Refactor pkg.fish to auto-detect the system package manager via
_fish_deps_detect_pm instead of hard-requiring paru/yay. Supports
install, uninstall, and auto (toggle) modes across paru, yay, pacman,
apt, dnf, zypper, yum, brew, and pkg. Package installed-checks now use
the correct query tool per PM (pacman -Qi, dpkg -s, rpm -q, etc.).
Also adds zypper to the _fish_deps_detect_pm detection priority list.
Replace all ad-hoc inline comments between license headers and function
declarations with consistent SYNOPSIS / DESCRIPTION / ARGUMENTS / RETURNS /
EXAMPLE blocks across all 99 project-owned functions/ files. No executable
logic, variable names, or exit codes were modified.
Completes Task #6 from AGENTS.md (Retroactive Function Documentation
Standardization).
Adds inline comments to all fish_add_path entries for self-documentation.
Removes the unused $HOME/Applications path. Changes cargo bin flag from
-mg to -mga so the cargo bin directory is appended to PATH rather than
prepended, avoiding conflicts with system-installed Rust tools.
Adds __fzf_inline_picker function and @@ keybinding (Emacs + all Vi
modes). Opens an fzf session and injects the selected item at the
cursor position in the current command line. Includes SYNOPSIS/
DESCRIPTION doc block per project conventions. Updates README with
new binding in the User Bindings table.
- mkdir: loop over path args calling _fish_mkdir_p --path; falls back
to command mkdir -p when flag args (e.g. -m 755) are present
- mkcd: default to _fish_mkdir_p --tree for new dirs; add -s/--silent
flag to suppress tree output (mkcd's own status message still prints)
- Add _fish_mkdir_p: reusable mkdir -p with three output modes:
--path (default): "Created: ~/full/path/" on one line
--tree: dimmed existing anchor + cyan tree of newly-created dirs
--silent: no output
HOME is substituted with ~ in all output paths
- Refactor poke to delegate to _fish_mkdir_p --tree; removes inline
mkdir/echo logic and gains ~ substitution and per-dir tree output
- Add poke: touch with automatic parent directory creation; prints
colored notice when new dirs are created; handles multiple file args
- Refactor config.fish CachyOS override block: consolidate copy into
the erase+source loop alongside ls/lt/cleanup
- fish-deps: replace most with ov (cargo crate + AUR pkg); add yay as
rec dep with yay-build special (paru -S yay or AUR makepkg); add
update handling for yay-build in _fish_deps_update
- README: document poke in Directory & File Listing table
Use a per-invocation temp ov config to set SectionLine Background/Foreground
to empty strings, preventing ov from overriding the ANSI colors embedded in
the starship prompt when it is pinned as a sticky section header.
Also adds a second return sentinel inside the interactive block of config.fish
to guard against tool-injected init lines that target the inner scope, and
updates README accordingly.
- logs.fish: add yay category, ov-powered viewing for paru/yay (section
headers, color highlights, ==> AUR build markers) and scrollback logs
(OSC 133;A sticky prompt headers); add fzf Ctrl-D delete with Y/n
confirm and list refresh, ? toggleable help overlay; run
_scrollback_prune_junk before building file list
- _scrollback_prune_junk: new utility to remove empty, single-line, and
Kitty tab-rename noise logs before display and before max-file pruning;
called from both logs and smart_exit
- smart_exit: call _scrollback_prune_junk before counting toward max files
- conf.d/yay-wrapper.fish: auto-generate ~/.local/bin/yay logging wrapper
mirroring paru-wrapper; tees output to timestamped logs, prunes old ones
- conf.d/starship.fish: move fish_prompt from config.fish; emit OSC 133;A
after the prompt's leading newline so the marker lands on the info-bar
line rather than the blank line above it; guard with type -q starship so
clean fish sessions use built-in markers unchanged
- config.fish: remove inline fish_prompt block (now in conf.d/starship.fish);
add return sentinel at EOF to prevent tool-injected init lines from running
- completions/ov.fish: add ov tab completions
- README.md: document all of the above
- Set $PAGER to ov in config.fish (falls back to less); remove LESS=-R
- Rewrite less wrapper with full hierarchy: $PAGER → ov → less → more → cat
- Simplify view.fish fallback to delegate to the less wrapper
- Add logs function: fzf browser for scrollback and paru logs, opens in $PAGER
- Add claude wrapper: auto-injects --remote-control unless already present
- Add conf.d/paru-wrapper.fish: generates ~/.local/bin/paru on first run,
versioned so future template changes auto-propagate on next shell start
- Sync README.md and requirements.md to document all of the above
- Add smart_exit function: captures Kitty scrollback to a timestamped
log file on exit; --no-log/-n skips capture; auto-prunes oldest logs
once count exceeds SCROLLBACK_HISTORY_MAX_FILES
- Wire exit → smart_exit in config.fish for interactive sessions;
export SCROLLBACK_HISTORY_DIR and SCROLLBACK_HISTORY_MAX_FILES with
sane defaults (~/.terminal_history and 100 respectively)
- Update cat to detect files in SCROLLBACK_HISTORY_DIR or containing
raw ANSI escape sequences and pass them through command cat instead
of bat, preserving color output
- Remove redundant alias rm="rm -i" from tricks.fish (superseded by
functions/rm.fish trash-aware wrapper)
- Sync README: new Scrollback History integration section, smart_exit
added to System functions table, cat description updated, stale rm
Safety Wrapper entry and note removed
- Add system aliases: dot-navigation (.., ..., etc.), color overrides for
grep/dir/vdir, safety wrappers (cp/mv/rm -i), archive shortcuts
(tarnow, untar), wget resume, tb (termbin), and jctl
- Set MANPAGER/MANROFFOPT to render man pages through bat when available
- Configure franciscolourenco/done notification plugin settings
(__done_min_cmd_duration=10s, __done_notification_urgency_level=low)
- Add psmem/psmem10 memory-monitoring helpers
- Switch PATH setup to fish_add_path (handles deduplication automatically)
- Add conf.d/done.fish (done plugin v1.19.1)
- Source tricks.fish explicitly after CachyOS base config in config.fish
- Sync README with all new functions, aliases, and integrations
Adds conf.d/tricks.fish (PATH additions for ~/.local/bin and depot_tools,
bang-bang key bindings, history timestamp override, backup utility) and
functions/copy.fish (smarter cp wrapper that strips trailing slashes from
source directories, fixing a CachyOS-specific cp quirk).
Updates config.fish to explicitly source copy.fish on startup and refactors
several conditional blocks to single-line style for consistency. Syncs
README.md to document all new utilities.
Creates a directory (including all missing parents) and immediately
cd's into it. Supports -h/--help, distinguishes new vs existing dirs
in feedback, and uses set_color for consistent colored output.
2026-05-27 15:30:08 -04:00
334 changed files with 51025 additions and 2153 deletions
about:fish-config is developed on Gitea. If you came from the GitHub mirror, please file here instead — the mirror is read-only and issues opened there are easy to miss.
A feature-rich Fish shell configuration for CachyOS (Arch Linux), built around a Catppuccin Mocha aesthetic with a curated set of modern CLI tool integrations, smart shell functions, and a heavily customized abbreviation system for keyboard-driven workflows.
A feature-rich Fish shell configuration for CachyOS (Arch Linux),
built around a Catppuccin Mocha aesthetic with a curated set of modern
CLI tool integrations, smart shell functions, and a heavily customized
abbreviation system for keyboard-driven workflows.
@@ -24,519 +26,147 @@ A feature-rich Fish shell configuration for CachyOS (Arch Linux), built around a
This config layers on top of the CachyOS base Fish configuration and adds:
- **Catppuccin Mocha** theming throughout (prompt, FZF, Zellij)
- **Starship** prompt with VI key bindings
- **Fisher** plugin management with FZF key bindings and Catppuccin syntax colors
- **Catppuccin Mocha** theming throughout (prompt, FZF, syntax highlighting)
- **Starship** prompt with VI key bindings; Catppuccin Mocha nim-style fallback prompt when Starship is absent or C3 overrides are disabled
- **Fisher** plugin manager bootstrapped automatically; manages `sponge` (failed-command history filter); FZF bindings, Catppuccin theme, done, autopair, and puffer-fish are bundled directly with the config as customized versions
- **Smart CLI wrappers** that prefer modern tools (`eza`, `bat`, `btop`, `dust`, `prettyping`) with graceful fallbacks
- **Auto Python venv** activation on directory change (direnv-aware)
- **Kitty terminal** deep integration for splits, tabs, and SSH
- **AI workflow** helpers for Claude and Gemini session management
- **Named background jobs** — `jobrunner` (short: `jr`) starts, lists, inspects, re-attaches to, and kills detached tasks via `tmux` or GNU `screen`, so long-running work survives closing the shell
- **Optional session logging** — terminal scrollback, multiplexer panes (tmux/zellij), and AUR-helper output can be captured to `~/.terminal_history`; **off by default**, opt in when you want it (see the caution below and [Session Logging](#session-logging))
- **AI workflow** helpers for Claude and Antigravity session management
- **WakaTime** shell activity tracking
- **Opt-out toggles** for every opinionated component — see [Minimal Mode](#minimal-mode)
> [!CAUTION]
> **This configuration *can* log your terminal sessions to disk.** Logging is
> **off by default** — but once enabled it silently captures terminal output to
> `~/.terminal_history`: Kitty scrollback when a window closes, live tmux pane
> streams, zellij pane snapshots on exit, and full `paru`/`yay` output. These
> logs can contain command output, file contents, and anything else printed to
> your terminal. Nothing is sent off your machine, but the files persist
> locally until pruned.
>
> To turn logging on, set the C5 category variable:
>
> ```fish
> set -U __fish_config_op_logging on
> ```
>
> Or run **`config-settings`** for an interactive menu to flip logging (and any
> other opinionated category) on or off — no variable names to remember.
>
> This takes effect immediately in every open shell. See [Session Logging](#session-logging)
> for exactly what is captured and where, and [Minimal Mode](#minimal-mode) for the
Never edit the generated `docs/fish-config.md` — it's rebuilt from all
three sources and any hand-edits are discarded.
See [FZF Bindings](#fzf-bindings) under Key Bindings for the default FZF shortcuts.
---
## Integrations
> [!NOTE]
> All integrations listed below are designed to gracefully fallback to basic commands or safely ignore their configuration if their required external dependencies are not installed on the system.
### Zoxide
Smart `cd` replacement powered by frecency scoring. `cd`, `z`, and `cdi`/`zi` are all mapped to zoxide-backed navigation functions.
To browse the docs from the terminal:
| Command | Description |
|---|---|
| `cd <path>` / `z <path>` | Jump to a matching directory by frecency; falls back to exact path |
| `cdi` / `zi` | Open an interactive fzf selector across all frecency-ranked directories |
| `help config` | Open the terminal manual in the best available pager |
| `help config <keyword>` | Jump directly to a section matching the keyword |
| `help config --html` | Open the documentation site in the default browser |
| `help config --man` | Open the compiled man page via `man -l` |
| `help config <keyword> --man` | Open the man page jumping to the nearest match |
| `repo-open` | Open this repo's web page in the browser (deep-links to the current branch and sub-directory) |
Tab completions for `cd` and `z` blend standard directory entries (CWD and `CDPATH`) with zoxide frecency results, so familiar paths and frequently-visited destinations appear together in a single list. Full tab completions for the `zoxide` CLI itself (subcommands: `add`, `query`, `remove`, `import`, `init`) are provided via `completions/zoxide.fish`.
The pager falls back through: **ov** → **bat** → **man -l** → **less** → **cat**.
### DirEnv
Automatically loads `.envrc` files on directory change. Takes priority over the built-in auto-venv logic.
### Auto Python Venv
When entering a directory containing a `.venv/`, the virtualenv is automatically activated.
It is automatically deactivated when you leave the project tree.
> [!TIP]
> DirEnv-managed directories are skipped by the auto-venv logic to avoid conflicts.
### WakaTime
Every shell command is reported to WakaTime for time-tracking. Disable by setting `FISH_WAKATIME_DISABLED=1`.
### Tailscale
Full tab completion for the `tailscale` CLI is provided via `conf.d/tailscale.fish`.
---
## Key Bindings
### FZF Bindings
These are the default FZF bindings (from `fzf.fish`):
| Binding | Action |
|---|---|
| `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 |
### User Bindings
Beyond standard shell and FZF bindings, these custom interactive shortcuts are available:
| Binding | Action | Description |
|---|---|---|
| `Ctrl+G` | Previous Path Head | Behaves like `!$:h` in Bash. Inserts the directory part of the previous command's last argument. |
| `Ctrl+F` | Interactive History Substitution | Behaves like `!!:s/old/new/` in Bash. Performs substitution on the previous command using `old/new` syntax. When no text is entered, prepends `sudo` to the previous command. The `old/new/n` syntax will perform substitution on the command `n` lines previous in the history. |
| `Ctrl+Alt+U` | Replace Command Token | Strips the first token (the command) from the current line. **If the line is empty**, it pulls the previous command and strips its first token, placing the cursor at the start for a quick replacement (e.g., changing `mkdir` to `cd` while keeping the paths). |
| `Ctrl+Alt+=` | Inline Qalculate! Evaluation | Passes the current command-line buffer to `qalc` (Qalculate!) and prints the result, then clears the buffer. Allows rapid-fire math without leaving the shell — type `150 * 1.08`, press `Ctrl+Alt+=`, and see `162` immediately. |
| `Ctrl+Enter` | Smart Execute | Context-aware Enter key. Empty buffer → standard Enter. Buffer ending with `=` → evaluates it as a math expression via `qalc` (same as `Ctrl+Alt+=`). Any other content → executes the command normally. |
---
## Functions
### Modern CLI Replacements
These functions wrap modern alternatives with graceful fallbacks to standard tools.
| Function | Replaces | Tool |
|---|---|---|
| `ls` | `ls` | `eza` (falls back to `lsd`, then system `ls`) |
| `cat` | `cat` | `bat` (plain, no pager) |
| `less` | `less` | `most` |
| `ping` | `ping` | `prettyping --nolegend` |
| `top` | `top` | `btop` |
| `rg` | `rg` | ripgrep with `--hyperlink-format=kitty` |
| `ltr` | `eza` — long listing, reversed modification time, age color scale |
| `lD` | `eza` — directories only |
| `lx` | `eza` — long listing sorted by extension |
| `lt` | `eza` — tree listing, depth 2 |
| `lstree` | `eza` — full recursive tree |
### Git
| Function | Description |
|---|---|
| `branch` | Switch to or create a git branch |
| `gitup` | Fetch updates and show git status |
| `git-clean` | Fetch, prune, update current branch, delete orphaned local branches |
| `git-clean --force` | Same but force-deletes unmerged orphaned branches |
| `clone` | `clone-in-kitty` wrapper |
| `gitui` | Fast terminal Git UI |
| `gi` | Generate and append `.gitignore` patterns from gitignore.io; `gi` (no args) appends boilerplate then prompts interactively; `gi <targets>` appends named patterns; `gi -s <targets>` prints to stdout; `gi -l` lists all targets |
### Package Management (Arch / paru)
| Function | Description |
|---|---|
| `pkg <name>...` | Toggle package: installs if missing, removes (`-Rns`) if installed; `-i` force-install, `-u` force-uninstall |
| `fzf-update` | Install or upgrade fzf from git HEAD into `~/.fzf` (guarantees the latest build) |
| `check_fish_deps` | Legacy alias — delegates to `fish-deps status` |
Install method priority: **git+cargo source build** (fish) → **cargo** (other Rust tools, gets latest crate) → **system PM** (paru/apt/brew/etc.) → **git clone** (fzf) → **curl installer** (starship, fisher) → **pipx** (Python tools). When multiple methods are available for a tool, you are prompted to choose.
> [!NOTE]
> Upgrading Fish from source requires **cargo** and **[uv](https://docs.astral.sh/uv/)**. Both are managed dependencies — `fish-deps install` will offer to install them before attempting the Fish build. If both are unavailable, `fish-deps update` falls back to the system package manager.
### Docker
| Function | Description |
|---|---|
| `ld` / `lzd` | Launch LazyDocker using the currently active Docker context |
| `antigravity` | Wrapper for `agy` (antigravity-cli) that suppresses a noisy warning |
| `antigravity-ide` | Wrapper for `antigravity-ide` binary that suppresses a noisy warning |
| `bash` | Drop into bash (raw Fish session via `rawfish`) |
---
## Abbreviations
Abbreviations expand in-place as you type, keeping your history clean.
### History Expansions (Bash-style)
These abbreviations replicate Bash's bang-style history expansions. They expand anywhere in the command line when a trigger key (like `Space` or `Enter`) is pressed.
| Abbr | Expansion | Description |
|---|---|---|
| `!^` | First argument | Expands to the first argument of the previous command |
| `!*` | All arguments | Expands to all arguments of the previous command |
| `!-n` | n-th previous | Expands to the n-th previous command in history (e.g., `!-2`) |
| `!string` | Prefix search | Expands to the most recent command starting with `string` |
| `!?string?` | Contains search | Expands to the most recent command containing `string` |
| `^old^new` | Quick substitution | Replaces `old` with `new` in the previous command and expands to it |
These abbreviations mirror Vim/tmux ergonomics for managing terminal splits, tabs, and windows. They automatically detect whether you are using Kitty or WezTerm and execute the appropriate terminal CLI commands.
| Abbr | Action |
|---|---|
| `:q` | Close active pane |
| `:Q` | Close active tab |
| `:w` | New OS window |
| `:t` | New tab |
| `:wv` | Horizontal split |
| `:wh` | Vertical split |
| `:tp` / `:tn` | Navigate tabs left/right |
| `:tl "Title"` | Rename current tab |
| `:tgn` | New tab in `~/.config/nvim` |
| `:tgf` | New tab in `~/.config/fish` |
| `:tgp` | New tab in `~/projects` |
| `:tgr` | New root tab (`sudo -i`) |
### SSH
Machine-specific SSH abbreviations (e.g. `sshr`, `sshrt`) live in `~/.config/.user-dots/fish/local.fish`.
(See [Personalization](#personalization) for examples)
### Docker
| Abbr | Expands To |
|---|---|
| `dcl` | `docker context use default` |
| `dcls` | `docker context ls` |
| `lzd` | `ld` (LazyDocker) |
Named context shortcuts (e.g. `dcr`, `dck`) live in `~/.config/.user-dots/fish/local.fish`.
(See [Personalization](#personalization) for examples)
### Systemctl
| Abbr | Expands To |
|---|---|
| `sc` | `systemctl` |
| `ssc` | `sudo systemctl` |
| `scu` | `systemctl --user` |
| `st` | `systemctl status` |
| `scs` | `systemctl start` |
| `scr` | `systemctl restart` |
| `ssct` | `sudo systemctl status` |
| `sscs` | `sudo systemctl start` |
| `sscr` | `sudo systemctl restart` |
### Speed Test
| Abbr | Expands To |
|---|---|
| `speedtest-fast` | `fast-cli` (speed test via fast.com) |
### Beads (bd)
| Abbr | Expands To |
|---|---|
| `bl` | `bd list` |
| `bs` | `bd sync` |
| `bC` | `bd create --title` |
| `bsh` | `bd show` |
| `lb` | `lazybeads` |
---
## Dependencies
### Required
| Tool | Version | Purpose |
|---|---|---|
| [uv](https://docs.astral.sh/uv/) | any | Python runner (needed to build Fish from source) |
| [Rust / cargo](https://www.rust-lang.org/tools/install) | any | Installs Rust-based tools; required to build Fish |
| [Fisher](https://github.com/jorgebucaran/fisher) | any | Plugin manager |
| [Starship](https://starship.rs/) | any | Prompt |
| [fzf](https://github.com/junegunn/fzf) | any | Fuzzy finder |
| [zoxide](https://github.com/ajeetdsouza/zoxide) | any | Smart directory jumper |
| [direnv](https://direnv.net/) | any | Per-directory env loading |
> [!WARNING]
> Fish **4.0 or newer is required.** This config uses `test` syntax and other constructs that are incompatible with Fish 3.x. Older versions will produce errors on startup.
> Run `fish-deps install` or `fish-deps update` to upgrade — it will install `uv` and `cargo` automatically if missing, then build the latest Fish from source.
For a complete, categorized list of all non-standard tools required or used by this configuration, see [requirements.md](requirements.md).
> **Note:** `fish-config` (hyphen) is this configuration's man page. `fish_config` (underscore) is fish's built-in browser-based configuration tool — a completely separate command. Don't mix them up.
Then open a new Fish shell — Fisher and all plugins will be installed automatically on first launch, and the Catppuccin Mocha theme will be applied.
Then open a new Fish shell — Fisher will be installed automatically on first launch and the Catppuccin Mocha theme will be applied. All plugin functionality is bundled directly with this config and requires no additional installation.
A [chezmoi](https://www.chezmoi.io/) dotfile manager is also configured — secrets are sourced from `~/.config/.user-dots/fish/secrets.fish` and excluded from version control.
A [chezmoi](https://www.chezmoi.io/) dotfile manager is also configured — secrets are kept in a private overlay directory (see [Personalization](#personalization)) and excluded from version control.
**External requirements.** Everything degrades gracefully if a tool is missing, with two exceptions worth calling out. `python3` is required by the documentation pipeline and by `config-settings`, whose TUI is drawn with the stdlib `curses` module. That module ships with CPython on Arch, Fedora and a full Debian/Ubuntu `python3`; `python3-minimal` alone does **not** carry `_curses`, so install the complete `python3` package there. `config-settings` checks for both and tells you which is missing rather than failing inside the renderer.
> [!IMPORTANT]
> `config.fish` ends with a `return` sentinel guard. Any lines appended **after** it by a tool's setup command will silently have no effect. Many tools (starship, zoxide, mise, etc.) offer a setup command that appends an `init | source` line to your `config.fish` — all integrations are managed through `conf.d/` files instead. If you add a new tool and its shell integration appears to do nothing, check whether its setup command appended an init line to the bottom of `config.fish` and create a `conf.d/<tool>.fish` file for it instead.
### Updating the Config
Pull the latest changes from upstream without needing a configured git remote:
| Command | Description |
|---|---|
| `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 |
---
## Personalization
Sensitive credentials and machine-specific paths are kept out of version control via a secondary private directory at `~/.config/.user-dots/fish/`. Two files are sourced automatically by `config.fish` if they exist:
Sensitive credentials and machine-specific paths are kept out of version control via a private overlay directory. The path defaults to `~/.config/.user-dots/fish/` but can be changed by setting a universal variable:
`config.fish` sources `local.fish` from that directory. `local.fish` is responsible for sourcing its own `secrets.fish` companion:
```
~/.config/.user-dots/fish/
$__fish_user_dots_path/
├── secrets.fish # API keys, tokens, passwords, personal identifiers
└── local.fish # Machine-specific paths and environment variables
└── local.fish # Machine-specific paths, env vars, and sourcing secrets
```
### secrets.fish
@@ -616,25 +268,106 @@ abbr -a dcw 'docker context use work-server'
### How it works
`config.fish` sources both files with an existence check so the public config works cleanly on any machine that doesn't have the private repo:
`config.fish` sources only `local.fish` with an existence check so the public config works cleanly on any machine without the private repo. `local.fish` is responsible for sourcing its own `secrets.fish`:
For convenience, a git-ignored `user-dots` symlink in the fish config directory is pointed at `$__fish_user_dots_path` on startup, so the overlay can be browsed from `~/.config/fish/`. It is recreated if missing and repointed if the path variable changes. Creation is a C2 startup side-effect (`__fish_config_op_autoexec`); it only ever manages a symlink and never clobbers a real file or directory at that path.
To opt out, set `__fish_user_dots_symlink` to a falsy value (or toggle **Dots link** off on the **Paths** page of `config-settings`). Disabling it stops the symlink being generated and removes any existing one immediately — honoured regardless of the C2 master switch.
`fish_variables` (which fish auto-manages and may contain universal variable state) is excluded from this repo via `.gitignore`.
---
## Minimal Mode
Everything opinionated in this config — command shadows, startup side-effects, key and environment overrides, terminal integrations, and the first-run greeting — is active by default but can be switched off. Logging (C5) is the exception: it is **opt-in**, off until you explicitly enable it.
> **The easy way — `config-settings`:** Run `config-settings` for an interactive TUI that manages settings across four pages — **Universal** and **Session** (the opinionated category toggles below, persistent or per-shell), **Sponge** (history-scrubbing: delay, exit codes, purge-on-exit, and extra sensitive variable names), and **Paths** (scrollback log dir, max files, and the user-dots path) — without typing a single variable name. Navigate with the arrow keys (or `h`/`j`/`k`/`l`); toggle rows step OFF ← DEFAULT → ON, value rows edit inline with `Enter` and reset with `←`. `Enter` on a category opens its sub-categories, `/` filters the page — reaching into sub-categories too, listed as `Category › Sub` — `?` opens a help overlay, `Tab`/`Shift-Tab` cycle pages, and `q` applies your edits and quits. Edits are collected as you make them and written in one batch on exit; the status bar shows the pending count. The panel is drawn with Python's stdlib `curses`, so it resizes with the terminal and never flickers — see [Installation](#installation) for the `python3` requirement.
If you'd rather set them by hand, each category is controlled by a universal variable. Six category toggles and one master switch are available:
| Variable | Disables |
|---|---|
| `__fish_config_op_aliases` | Command shadows: `ls`→eza, `cat`→bat, `cd`→zoxide, `rm`→trash, `top`→btop, `edit`→multi-editor launcher, and friends; `grep`/`cp`/`mv`/`wget` flag injection |
| `__fish_config_op_greeting` | Per-session `fish_greeting` (suppresses distro greetings such as CachyOS fastfetch by overriding with an empty function); first-run welcome banner |
| `__fish_config_opinionated` | Master switch — disables all six categories at once (it is a master *off* switch; it cannot enable opt-in C5 logging) |
Set any of them to a falsy value (`0`, `false`, `no`, `off`, `n`) to disable; erase the variable to re-enable. An explicit per-category truthy value overrides a falsy master switch, so you can disable everything with `__fish_config_opinionated=0` and selectively re-enable individual categories:
```fish
# Plain shell: disable everything opinionated
set-U__fish_config_opinionated0
# Or pick a single category, e.g. keep integrations but drop command shadows
set-U__fish_config_op_aliases off
# Minimal mode but keep the greeting (per-category overrides master)
set-U__fish_config_opinionated0
set-U__fish_config_op_greeting1
# Opt in to session logging (C5 is off by default)
set-U__fish_config_op_logging on
# Back to full flavor
set-Ue__fish_config_opinionated
set-Ue__fish_config_op_greeting
```
Command shadows react immediately; bindings, prompt, and abbreviations take effect in new shells. With aliases disabled, `rm` deletes permanently again instead of trashing. See `help config opinionated` for the full component list.
Each category further sub-divides into two to six sub-categories with
their own `__fish_config_op_<category>_<subcategory>` toggles (e.g.
`__fish_config_op_aliases_filesystem`), following the exact same
truthy/falsy/unset cascade one level deeper. Run `config-settings` and
press Enter on a category row to browse and toggle its sub-categories —
or press `/` and type, which searches sub-categories across every
category at once and lists the hits as `Category › Sub`. Or see the
Runs before every push (and gates the [documentation build](.github/workflows/ci.yml) in CI, so a broken config can't get published): syntax-lints every `.fish` file, then loads the config in an isolated `HOME`/XDG sandbox — never this checkout itself, since it doubles as a real `~/.config/fish` — and runs functional checks against foundational behavior (XDG/PATH/CDPATH setup, key bindings, abbreviations, core functions, the opinionated-component registry, and more).
---
## Contributing
Interested in contributing? See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the
branching/PR workflow, commit conventions, fish coding standards, and the
is the base repository. [github.com/rootiest/fish-config](https://github.com/rootiest/fish-config)
is a push-mirror of it — identical content, but one-way and read-only from a
contributor's perspective. Branches, forks, and merges made on the GitHub
side aren't fed back upstream, so they risk being silently overwritten by
the next mirror push. Until two-way sync exists, please fork, branch, and
open issues/PRs from the Gitea repository rather than the GitHub mirror.
---
## Attribution
The core of the [Zoxide integration](#zoxide) in this repository was originally adapted from the [icezyclon/zoxide.fish](https://github.com/icezyclon/zoxide.fish) plugin (MIT Licensed) and has since been heavily customized for performance and Fish 4.x compatibility.
The core of the [Zoxide integration](https://fish.rootiest.fyi/02-path-setup/) in this repository was originally adapted from the [icezyclon/zoxide.fish](https://github.com/icezyclon/zoxide.fish) plugin (MIT Licensed) and has since been heavily customized for performance and Fish 4.x compatibility.
complete -c copilot -l agent -r -d 'Specify a custom agent to use'
complete -c copilot -l resume -s r -r -d 'Resume from a previous session (optionally specify existing session ID, task ID, ID prefix, or name;name matching is exact, case-insensitive)'
complete -c copilot -l continue -f -d 'Resume the most recent session'
complete -c copilot -l name -s n -r -d 'Set a name for the new session'
complete -c copilot -l session-id -r -d 'Resume an existing session or task by ID, or setthe UUID for a new session'
complete -c copilot -l connect -r -d 'Connect directly to a remote session (optionally specify session ID or task ID)'
complete -c copilot -l allow-all-tools -f -d 'Allow all tools to run automatically without confirmation;required for non-interactive mode'
complete -c copilot -l allow-all-paths -f -d 'Disable file path verification and allow access to any path'
complete -c copilot -l disallow-temp-dir -f -d 'Prevent automatic access to the system temporary directory'
complete -c copilot -l no-custom-instructions -f -d 'Disable loading of custom instructions from AGENTS.md and related files'
complete -c copilot -l no-auto-update -f -d 'Disable downloading CLI update automatically (disabled by default in CI environments)'
complete -c copilot -l no-ask-user -f -d 'Disable the ask_user tool (agent works autonomously without asking questions)'
complete -c copilot -l extension-sdk-path -r -d 'Override the bundled @github/copilot-sdk injected into extension subprocesses with a local `copilot-sdk/` folder. Invalid paths fall back to the bundled SDK.'
complete -c copilot -l log-level -r -d 'Set the log level' -a 'none error warning info debug all default'
complete -c copilot -l stream -r -d 'Enable or disable streaming mode' -a 'on off'
complete -c copilot -l output-format -r -d 'Output format: \'text\'(default) or \'json\'(JSONL, one JSON object per line)' -a 'text json'
complete -c copilot -l share -r -d 'Share session to markdown file after completion in non-interactive mode (default: ./copilot-session-<id>.md)'
complete -c copilot -l share-gist -f -d 'Share session to a secret GitHub gist after completion in non-interactive mode'
complete -c copilot -l add-dir -r -d 'Add a directory to the allowed list for file access (can be used multiple times)'
complete -c copilot -l attachment -r -d 'Attach a file (image or native document) to the initial prompt;only valid in non-interactive mode (can be used multiple times)'
complete -c copilot -l disable-mcp-server -r -d 'Disable a specific MCP server (can be used multiple times)'
complete -c copilot -l enable-all-github-mcp-tools -f -d 'Enable all GitHub MCP server tools instead of the default CLI subset. Overrides --add-github-mcp-toolsetand--add-github-mcp-tool options.'
complete -c copilot -l add-github-mcp-toolset -r -d 'Add a toolset to enable for the GitHub MCP server instead of the default CLI subset (can be used multiple times). Use "all" for all toolsets.'
complete -c copilot -l add-github-mcp-tool -r -d 'Add a tool to enable for the GitHub MCP server instead of the default CLI subset (can be used multiple times). Use "*" for all tools.'
complete -c copilot -l plugin-dir -r -d 'Load a plugin from a local directory (can be used multiple times)'
complete -c copilot -l additional-mcp-config -r -d 'Additional MCP servers configuration as JSON string or file path (prefix with @)(can be used multiple times;augments config from ~/.copilot/mcp-config.json for this session)'
complete -c copilot -l allow-tool -r -d 'Tools the CLI has permission to use;will not prompt for permission'
complete -c copilot -l deny-tool -r -d 'Tools the CLI does not have permission to use;will not prompt for permission'
complete -c copilot -l available-tools -r -d 'Only these tools will be available to the model'
complete -c copilot -l excluded-tools -r -d 'These tools will not be available to the model'
complete -c copilot -l secret-env-vars -r -d 'Environment variable names whose values are stripped from shell and MCP server environments and redacted from output (e.g., --secret-env-vars=MY_KEY,OTHER_KEY)'
complete -c copilot -l allow-url -r -d 'Allow access to specific URLs or domains'
complete -c copilot -l deny-url -r -d 'Deny access to specific URLs or domains, takes precedence over --allow-url'
complete -c copilot -l allow-all-urls -f -d 'Allow access to all URLs without confirmation'
complete -c copilot -l allow-all -f -d 'Enable all permissions (equivalent to --allow-all-tools--allow-all-paths--allow-all-urls)'
complete -c copilot -l yolo -f -d 'Enable all permissions (equivalent to --allow-all-tools--allow-all-paths--allow-all-urls)'
complete -c copilot -l max-autopilot-continues -r -d 'Maximum number of continuation messages in autopilot mode'
complete -c copilot -l mode -r -d 'Set the initial agent mode' -a 'interactive plan autopilot'
complete -c copilot -n '__fish_seen_subcommand_from plugin;and__fish_seen_subcommand_from marketplace;and__fish_seen_subcommand_from remove' -l force -s f -f -d 'Force removal even if plugins are installed'
complete -c copilot -n '__fish_seen_subcommand_from mcp' -f -a list -d 'List configured MCP servers'
complete -c copilot -n '__fish_seen_subcommand_from mcp' -f -a get -d 'Show server details'
complete -c copilot -n '__fish_seen_subcommand_from mcp' -f -a add -d 'Add an MCP server'
complete -c copilot -n '__fish_seen_subcommand_from mcp' -f -a remove -d 'Remove an MCP server'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand clean"-s V -l version -d'Print version'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand config; and not __fish_seen_subcommand_from set show edit reset help"-s h -lhelp-d'Print help'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand config; and not __fish_seen_subcommand_from set show edit reset help"-s V -l version -d'Print version'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand config; and not __fish_seen_subcommand_from set show edit reset help"-f-a"set"-d'Set a configuration value'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand config; and not __fish_seen_subcommand_from set show edit reset help"-f-a"show"-d'Show current configuration'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand config; and not __fish_seen_subcommand_from set show edit reset help"-f-a"edit"-d'Open config file in $EDITOR'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand config; and not __fish_seen_subcommand_from set show edit reset help"-f-a"reset"-d'Reset configuration to defaults'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand config; and not __fish_seen_subcommand_from set show edit reset help"-f-a"help"-d'Print this message or the help of the given subcommand(s)'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand config; and not __fish_seen_subcommand_from set show edit reset help"-f-a set -d'Set a configuration value'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand config; and not __fish_seen_subcommand_from set show edit reset help"-f-a show -d'Show current configuration'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand config; and not __fish_seen_subcommand_from set show edit reset help"-f-a edit -d'Open config file in $EDITOR'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand config; and not __fish_seen_subcommand_from set show edit reset help"-f-a reset -d'Reset configuration to defaults'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand config; and not __fish_seen_subcommand_from set show edit reset help"-f-ahelp-d'Print this message or the help of the given subcommand(s)'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand config; and __fish_seen_subcommand_from set"-s h -lhelp-d'Print help'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand config; and __fish_seen_subcommand_from set"-s V -l version -d'Print version'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand config; and __fish_seen_subcommand_from show"-s h -lhelp-d'Print help'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand config; and __fish_seen_subcommand_from edit"-s V -l version -d'Print version'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand config; and __fish_seen_subcommand_from reset"-s h -lhelp-d'Print help'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand config; and __fish_seen_subcommand_from reset"-s V -l version -d'Print version'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand config; and __fish_seen_subcommand_from help"-f-a"set"-d'Set a configuration value'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand config; and __fish_seen_subcommand_from help"-f-a"show"-d'Show current configuration'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand config; and __fish_seen_subcommand_from help"-f-a"edit"-d'Open config file in $EDITOR'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand config; and __fish_seen_subcommand_from help"-f-a"reset"-d'Reset configuration to defaults'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand config; and __fish_seen_subcommand_from help"-f-a"help"-d'Print this message or the help of the given subcommand(s)'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand config; and __fish_seen_subcommand_from help"-f-a set -d'Set a configuration value'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand config; and __fish_seen_subcommand_from help"-f-a show -d'Show current configuration'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand config; and __fish_seen_subcommand_from help"-f-a edit -d'Open config file in $EDITOR'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand config; and __fish_seen_subcommand_from help"-f-a reset -d'Reset configuration to defaults'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand config; and __fish_seen_subcommand_from help"-f-ahelp-d'Print this message or the help of the given subcommand(s)'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand backup; and not __fish_seen_subcommand_from list restore stats clean help"-s h -lhelp-d'Print help'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand backup; and not __fish_seen_subcommand_from list restore stats clean help"-s V -l version -d'Print version'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand backup; and not __fish_seen_subcommand_from list restore stats clean help"-f-a"list"-d'List available backups'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand backup; and not __fish_seen_subcommand_from list restore stats clean help"-f-a"restore"-d'Restore a branch from backup'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand backup; and not __fish_seen_subcommand_from list restore stats clean help"-f-a"stats"-d'Show backup storage statistics'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand backup; and not __fish_seen_subcommand_from list restore stats clean help"-f-a"clean"-d'Remove old backups, keeping the most recent ones'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand backup; and not __fish_seen_subcommand_from list restore stats clean help"-f-a"help"-d'Print this message or the help of the given subcommand(s)'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand backup; and not __fish_seen_subcommand_from list restore stats clean help"-f-a list -d'List available backups'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand backup; and not __fish_seen_subcommand_from list restore stats clean help"-f-a restore -d'Restore a branch from backup'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand backup; and not __fish_seen_subcommand_from list restore stats clean help"-f-a stats -d'Show backup storage statistics'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand backup; and not __fish_seen_subcommand_from list restore stats clean help"-f-a clean -d'Remove old backups, keeping the most recent ones'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand backup; and not __fish_seen_subcommand_from list restore stats clean help"-f-ahelp-d'Print this message or the help of the given subcommand(s)'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand backup; and __fish_seen_subcommand_from list"-l repo -d'Show backups for a specific repository by name'-r
complete-c deadbranch -n"__fish_deadbranch_using_subcommand backup; and __fish_seen_subcommand_from list"-l current -d'Only show backups for current repository'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand backup; and __fish_seen_subcommand_from list"-s h -lhelp-d'Print help'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand backup; and __fish_seen_subcommand_from clean"-s y -l yes -d'Skip confirmation prompt'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand backup; and __fish_seen_subcommand_from clean"-s h -lhelp-d'Print help'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand backup; and __fish_seen_subcommand_from clean"-s V -l version -d'Print version'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand backup; and __fish_seen_subcommand_from help"-f-a"list"-d'List available backups'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand backup; and __fish_seen_subcommand_from help"-f-a"restore"-d'Restore a branch from backup'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand backup; and __fish_seen_subcommand_from help"-f-a"stats"-d'Show backup storage statistics'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand backup; and __fish_seen_subcommand_from help"-f-a"clean"-d'Remove old backups, keeping the most recent ones'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand backup; and __fish_seen_subcommand_from help"-f-a"help"-d'Print this message or the help of the given subcommand(s)'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand backup; and __fish_seen_subcommand_from help"-f-a list -d'List available backups'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand backup; and __fish_seen_subcommand_from help"-f-a restore -d'Restore a branch from backup'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand backup; and __fish_seen_subcommand_from help"-f-a clean -d'Remove old backups, keeping the most recent ones'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand backup; and __fish_seen_subcommand_from help"-f-ahelp-d'Print this message or the help of the given subcommand(s)'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand stats"-s d -l days -d'Treat branches older than N days as stale (default: from config or 30)'-r
complete-c deadbranch -n"__fish_deadbranch_using_subcommand stats"-s h -lhelp-d'Print help'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand stats"-s V -l version -d'Print version'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand completions"-s h -lhelp-d'Print help'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand completions"-s V -l version -d'Print version'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand help; and not __fish_seen_subcommand_from list clean config backup stats completions help"-f-a"list"-d'List stale branches'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand help; and not __fish_seen_subcommand_from list clean config backup stats completions help"-f-a"clean"-d'Delete stale branches (merged only by default, use --force for unmerged)'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand help; and not __fish_seen_subcommand_from list clean config backup stats completions help"-f-a"config"-d'Manage configuration'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand help; and not __fish_seen_subcommand_from list clean config backup stats completions help"-f-a"backup"-d'Manage backups'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand help; and not __fish_seen_subcommand_from list clean config backup stats completions help"-f-a"stats"-d'Show repository branch statistics'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand help; and not __fish_seen_subcommand_from list clean config backup stats completions help"-f-a"completions"-d'Generate shell completion scripts'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand help; and not __fish_seen_subcommand_from list clean config backup stats completions help"-f-a"help"-d'Print this message or the help of the given subcommand(s)'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand help; and __fish_seen_subcommand_from config"-f-a"set"-d'Set a configuration value'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand help; and __fish_seen_subcommand_from config"-f-a"show"-d'Show current configuration'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand help; and __fish_seen_subcommand_from config"-f-a"edit"-d'Open config file in $EDITOR'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand help; and __fish_seen_subcommand_from config"-f-a"reset"-d'Reset configuration to defaults'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand help; and __fish_seen_subcommand_from backup"-f-a"list"-d'List available backups'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand help; and __fish_seen_subcommand_from backup"-f-a"restore"-d'Restore a branch from backup'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand help; and __fish_seen_subcommand_from backup"-f-a"stats"-d'Show backup storage statistics'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand help; and __fish_seen_subcommand_from backup"-f-a"clean"-d'Remove old backups, keeping the most recent ones'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand help; and not __fish_seen_subcommand_from list clean config backup stats completions help"-f-a list -d'List stale branches'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand help; and not __fish_seen_subcommand_from list clean config backup stats completions help"-f-a clean -d'Delete stale branches (merged only by default, use --force for unmerged)'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand help; and not __fish_seen_subcommand_from list clean config backup stats completions help"-f-a config -d'Manage configuration'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand help; and not __fish_seen_subcommand_from list clean config backup stats completions help"-f-a backup -d'Manage backups'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand help; and not __fish_seen_subcommand_from list clean config backup stats completions help"-f-a stats -d'Show repository branch statistics'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand help; and not __fish_seen_subcommand_from list clean config backup stats completions help"-f-a completions -d'Generate shell completion scripts'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand help; and not __fish_seen_subcommand_from list clean config backup stats completions help"-f-ahelp-d'Print this message or the help of the given subcommand(s)'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand help; and __fish_seen_subcommand_from config"-f-a set -d'Set a configuration value'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand help; and __fish_seen_subcommand_from config"-f-a show -d'Show current configuration'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand help; and __fish_seen_subcommand_from config"-f-a edit -d'Open config file in $EDITOR'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand help; and __fish_seen_subcommand_from config"-f-a reset -d'Reset configuration to defaults'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand help; and __fish_seen_subcommand_from backup"-f-a list -d'List available backups'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand help; and __fish_seen_subcommand_from backup"-f-a restore -d'Restore a branch from backup'
complete-c deadbranch -n"__fish_deadbranch_using_subcommand help; and __fish_seen_subcommand_from backup"-f-a clean -d'Remove old backups, keeping the most recent ones'
| `$BUN_INSTALL/bin` | Bun runtime and global packages |
| `$NPM_CONFIG_PREFIX/bin` | Global npm packages |
| `~/.lmstudio/bin` | LM Studio CLI |
| `~/.resend/bin` | Resend CLI |
| `~/.fzf/bin` | `fzf` binary (git-installed) |
Cargo binaries are intentionally appended (lowest priority) to avoid
shadowing system-installed Rust tools.
NOTE: While these directories are merged with your system's existing `$PATH` values, any executables in the prepended directories above will override (shadow) system binaries of the same name.
TIP: This standard PATH setup is gated behind the opinionated component overrides toggle. If you prefer to manage your PATH completely manually, you can disable it by setting `__fish_config_op_overrides` to `0` (or toggle it off in the `config-settings` menu).
fish-deps manages these tools. Run `fish-deps` to check status,
`fish-deps install` to install missing Required/Recommended ones, or add
`--optional`, `--terminals`, or `--all` to also include the Optional and/or
Terminal Emulators tiers.
## Required
| Tool | Description |
|---|---|
| `fish` | Fish shell >= 4.0 |
| `fzf` | Fuzzy finder |
## Recommended
| Tool | Description |
|---|---|
| `cargo` | Rust toolchain (via rustup); used by `fish-deps` to install Rust-based tools and to build fish from source. All paths are gated on `type -q cargo` and degrade gracefully. |
| `starship` | Cross-shell prompt; loaded via `type -q starship` guard. Without it the Catppuccin nim-style fallback prompt activates. |
| `uv` | Python package and project manager (Astral); used by the fish-from-source build path in `fish-deps`. All consumers degrade gracefully without it. |
| `direnv` | Per-directory environment loading; integration is fully guarded with `type -q direnv`. Without it the direnv hook is simply not loaded and auto-venv activates normally. |
| `paru` | AUR helper (Arch only; preferred); guarded throughout — non-Arch systems silently skip AUR-specific paths. |
| `yay` | AUR helper (Arch only; fallback to paru); same guards apply. |
| `eza` | Modern `ls` replacement |
| `zoxide` | Smart cd with frecency |
| `lsd` | `ls` replacement (fallback to `eza`) |
| `bat` | Syntax-highlighted `cat` |
| `ov` | Modern pager (replaces `less`); also backs the `logs` viewer. Not a Rust crate, despite the name collision with an unrelated `ov` crate on crates.io. Prefers `go install github.com/noborus/ov@latest` when `go` is available (always gets the latest release, and covers distros like Debian/Ubuntu that don't package `ov` in their base repos); falls back to the system PM (AUR on Arch) otherwise. |
| `ripgrep` | Fast line search |
| `trash` | Safe delete (`trash-cli`); backs the `rm` and `scrub` wrappers. |
| `python3` | Standalone interpreter — used by the `paru`/`yay` log cleaner. Note: `uv` does not provide `python3` on PATH, and Arch's base does not include it, so it is listed separately. All consumers degrade gracefully without it. |
## Optional
Single-purpose tools that back one wrapper function (or less) and only
matter if you already use that specific tool. Skipped by
`fish-deps install`/`sync` unless you pass `--optional`.
| Tool | Description |
|---|---|
| `btop` | Modern resource monitor; backs the `top` wrapper (falls back to system `top`). |
| `dust` | Disk usage tree (Rust); one of two backends for the `du` wrapper (falls back to system `du`). |
| `duf` | Disk usage/free overview; the other backend for the `du` wrapper (falls back to system `du`). |
| `prettyping` | Colorized ping wrapper; backs the `ping` wrapper (falls back to system `ping`). |
| `go` | Go toolchain; only used to install `ov` via `go install` (see below), which gets the latest release and doesn't depend on your distro packaging `ov`. Package name varies by distro (`go` on Arch/Homebrew, `golang`/`golang-go` on Debian/Fedora) — install manually if the listed package name doesn't resolve on your system. |
| `lazygit` | Terminal git UI; only referenced by the `lg` abbreviation. |
| `docker` | Container runtime; gates the Docker context indicator in the right prompt and backs the `ld` wrapper. Both consumers are guarded with `type -q docker` and degrade gracefully without it. Installing the daemon package does not enable/start the service — do that yourself if you want it running. |
| `yt-dlp` | Video/media downloader; backs the `yt-dlp` wrapper function. The wrapper falls back to the system `yt-dlp` and the rest of the config works without it. |
| `screen` | GNU screen; fallback backend for `jobrunner` when `tmux` is unavailable. |
## Terminal Emulators
GPU-accelerated terminal emulators. Only one is ever relevant to a given
user — the one matching `$TERM` — so neither is installed by default.
Skipped by `fish-deps install`/`sync` unless you pass `--terminals` (or
`--all`).
| Tool | Description |
|---|---|
| `kitty` | GPU-accelerated terminal; unlocks kitty-specific abbreviations and `--hyperlink-format=kitty` in the `rg` wrapper when `$TERM = xterm-kitty`. |
| `wezterm` | GPU-accelerated terminal; unlocks WezTerm-specific abbreviations when it's the active terminal. |
## Integrations
Opt-in third-party services that require their own account/setup.
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.
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
# Turn it back off:
set -U __fish_config_op_logging off # or: set -Ue __fish_config_op_logging
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.
## Return Sentinel
`config.fish` ends with a return sentinel guard. Any lines appended after it by
a tool's setup command (`starship init fish | source`, `zoxide init fish | source`,
etc.) will have no effect. All integrations are managed via `conf.d/` files.
If a new tool'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/<tool>.fish` instead.
## Updating
Pull the latest changes from the upstream repository without needing a
configured git remote:
- `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
All git output is suppressed. Run `exec fish` after a successful update to reload.
---
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
rootiest
fishconfig-bot
Gitea Actions