From 8d6ca1797a3aeb23dabcaa77171a6d799b380eaa Mon Sep 17 00:00:00 2001 From: rootiest Date: Sun, 26 Jul 2026 03:52:02 -0400 Subject: [PATCH] docs(functions): merge remaining manual prose into function headers 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. --- functions/config-settings.fish | 43 +++++++++++++++++++++++++++++----- functions/config-update.fish | 2 +- functions/edit.fish | 2 -- functions/fish-deps.fish | 22 +++++++++++++++-- functions/kitty-logging.fish | 22 ++++++++++------- functions/logs.fish | 10 ++++++++ functions/repo-open.fish | 3 --- functions/yt-dlp.fish | 4 ++++ 8 files changed, 85 insertions(+), 23 deletions(-) diff --git a/functions/config-settings.fish b/functions/config-settings.fish index 43a24b5..b757437 100644 --- a/functions/config-settings.fish +++ b/functions/config-settings.fish @@ -11,17 +11,48 @@ # Opens an interactive full-screen TUI for managing fish config settings # across four pages: # -# Universal — opinionated-category toggles, persistent (set -U / set -Ue) -# Session — opinionated-category toggles, this shell only (set -g / set -eg) -# Sponge — sponge history-scrubbing settings (delay, codes, secrets …) -# Paths — scrollback log dir, log max, and user-dots path +# Universal — opinionated-category toggles (C1–C6) + master, persistent (set -U) +# Session — the same toggles, current shell only (set -g) +# Sponge — sponge history-scrubbing settings: delay, successful exit +# codes, purge-only-on-exit, allow-previously-successful, and +# extra sensitive variable-name tokens +# Paths — scrollback log directory, scrollback max files, the user-dots +# path, and the user-dots convenience symlink toggle (Dots link) # -# Toggle rows use ← / → (or h / l) to step OFF ← DEFAULT → ON. -# Value rows (Sponge, Paths) use Enter to edit inline; ← / h clears to default. +# Toggle rows use ← / → (or h / l) to step OFF ← DEFAULT → ON; DEFAULT erases +# the variable so the master switch / built-in default applies. Value rows +# (Sponge, Paths) use Enter to edit inline; ← / h clears to default. List rows +# (e.g. Extra secret, OK codes) accept values separated by commas and/or +# whitespace — "A, B", "A,B" and "A B" all yield the same two entries. # Tab / Shift-Tab cycle forward / backward through pages. # Changes apply immediately — no confirm step. Always available regardless of # __fish_config_opinionated state. # +# The Sponge and Paths pages always write universal variables — these are +# persistent, set-and-forget settings with no per-session scope. Editing a +# scrollback row updates both the __fish_scrollback_history_* source-of-truth +# variables and the exported SCROLLBACK_HISTORY_* mirrors, so the AUR/tmux/ +# zellij log wrappers (which read the exported names) see the change in the +# running session. +# +# The panel adapts to the terminal width automatically, selecting from four +# layout tiers (with a 6-column buffer on each side before stepping up to the +# next tier) and horizontally centering the box. The panel redraws within +# ~0.3 s of a terminal resize with no keypress required. +# +# COLUMNS >= 90 → 78-wide panel (most detail) +# COLUMNS >= 86 → 74-wide panel +# COLUMNS >= 82 → 70-wide panel +# COLUMNS < 82 → 52-wide panel (default) +# +# Navigation: +# ↑ ↓ / k j Move cursor +# ← → / h l Toggle rows: OFF ← DEFAULT → ON +# ← / h Value rows: clear to default +# Enter Value rows: edit inline (Sponge / Paths pages) +# Tab / S-Tab Next / previous page +# q / Escape Exit +# # ARGUMENTS # -h, --help Print usage and exit # diff --git a/functions/config-update.fish b/functions/config-update.fish index 126a74c..0489e1b 100644 --- a/functions/config-update.fish +++ b/functions/config-update.fish @@ -13,7 +13,7 @@ # The remote URL is hard-coded so the update works even if the local clone # has no configured remote. Git output is suppressed; status is reported # through colored messages. After a successful pull the function prints a -# short summary of changed files. +# short summary of changed files; run `exec fish` to reload the shell. # # ARGUMENTS # -h, --help Show this help message and exit diff --git a/functions/edit.fish b/functions/edit.fish index 0fcd2c7..5bb66c4 100644 --- a/functions/edit.fish +++ b/functions/edit.fish @@ -41,8 +41,6 @@ # edit --terminal --new todo.md # edit --editor=code --clipboard # edit --text="hello world" -# edit ~/.config/fish/config.fish -# edit --visual notes.txt function edit --description 'Open files in a terminal or GUI editor with fallbacks' set -l c_head (set_color --bold cyan) set -l c_cmd (set_color --bold white) diff --git a/functions/fish-deps.fish b/functions/fish-deps.fish index 0aac7d8..90449f2 100644 --- a/functions/fish-deps.fish +++ b/functions/fish-deps.fish @@ -8,8 +8,26 @@ # fish-deps [status|install|update|sync] # # DESCRIPTION -# Manages fish shell dependencies by dispatching to subcommand handlers. -# Defaults to status when no subcommand is given. +# Unified command for managing all tools this configuration depends on, +# dispatching to subcommand handlers. Defaults to status when no subcommand +# is given. +# +# Install method priority (highest to lowest): +# 1. git+cargo source build (fish shell itself) +# 2. cargo (Rust tools — gets latest crate version) +# 3. system PM (paru/apt/brew/etc.) +# 4. git clone (fzf) +# 5. curl installer (starship, fisher, uv) +# +# When multiple methods are available you are prompted to choose. +# +# Dependencies are grouped into three tiers: +# +# Required fish, fzf, zoxide +# Integrations wakatime, tailscale +# Recommended cargo, starship, uv, direnv, paru, yay, eza, lsd, bat, +# btop, dust, duf, prettyping, ov, ripgrep, lazygit, +# lazydocker, trash, kitty, wezterm, python3, yt-dlp # # ARGUMENTS # status Report installed/missing deps (default) diff --git a/functions/kitty-logging.fish b/functions/kitty-logging.fish index 70bf46d..a0fb79e 100644 --- a/functions/kitty-logging.fish +++ b/functions/kitty-logging.fish @@ -8,17 +8,21 @@ # kitty-logging [install | uninstall | status | dismiss] [-h] # # DESCRIPTION -# Manages the fish-config Kitty scrollback watcher. `install` copies the -# canonical watcher into the Kitty config dir and wires it into kitty.conf via -# a sentinel-marked managed block (commenting out any conflicting active -# watcher line to avoid double-capture). `uninstall` reverses it. `status` -# reports wiring, watcher version, and C5 logging state. `dismiss` silences the -# per-session setup reminder. Runtime capture remains gated by the C5 -# .logging_disabled sentinel; install affects future Kitty instances only. +# Manages the fish-config Kitty scrollback watcher that powers C5 logging. +# `install` symlinks the canonical watcher into the Kitty config dir (so it +# always tracks the source) and wires it into kitty.conf via a +# sentinel-marked managed block, commenting out any conflicting active +# watcher line to avoid double-capture. `uninstall` reverses it. `status` +# reports wiring, installed watcher version, and C5 logging state. `dismiss` +# silences the per-session setup reminder. +# +# Runtime capture stays governed by the C5 .logging_disabled sentinel, so +# disabling __fish_config_op_logging makes the watcher inert without +# uninstalling. Install affects new Kitty windows only. # # ARGUMENTS -# install Copy the watcher and add the managed block to kitty.conf -# uninstall Remove the managed block and the installed watcher +# install Symlink the watcher and add the managed block to kitty.conf +# uninstall Remove the managed block and the watcher symlink # status Report wiring, watcher version, and C5 logging state # dismiss Stop the per-session reminder # -h, --help Show this help diff --git a/functions/logs.fish b/functions/logs.fish index b32ae91..14f2825 100644 --- a/functions/logs.fish +++ b/functions/logs.fish @@ -11,6 +11,16 @@ # Interactively browses terminal log files (scrollback, paru, yay) sorted # newest-first using fzf. Supports viewing in $PAGER, editing, and deletion. # +# Keybindings inside the fzf browser: +# Enter Open in $PAGER +# Ctrl+E Open in $EDITOR +# Ctrl+D Delete (with confirmation) +# ? Toggle keybind help overlay +# +# Paru and yay logs open in ov with syntax highlighting and sticky section +# headers. Scrollback logs open in ov with per-command sticky prompt headers +# based on OSC 133 markers. +# # ARGUMENTS # -h, --help Show help message # -c, --category cat Filter to one category: scrollback, paru, or yay diff --git a/functions/repo-open.fish b/functions/repo-open.fish index 4952029..c9f0375 100644 --- a/functions/repo-open.fish +++ b/functions/repo-open.fish @@ -42,9 +42,6 @@ # repo-open # open current branch (+ subdir) in browser # repo-open --print # just print the URL # repo-open --root # repo home page for the current branch -# repo-open -# repo-open --print -# repo-open --root # # NOTES # Typo abbreviation: open-repo (expands to repo-open on space/enter). diff --git a/functions/yt-dlp.fish b/functions/yt-dlp.fish index b9eb35c..6af9714 100644 --- a/functions/yt-dlp.fish +++ b/functions/yt-dlp.fish @@ -15,6 +15,10 @@ # drops our --embed-thumbnail). All other arguments pass through # untouched. --help and friends fall through to real yt-dlp. # +# Opinionated component (C1): when disabled via __fish_config_op_aliases +# (or the __fish_config_opinionated master), passes straight through to +# the system yt-dlp with no defaults injected. +# # ARGUMENTS # args... Arguments forwarded to yt-dlp (defaults prepended) # --no-embed-thumbnail Skip thumbnail embedding for this run