From d3851fcddce6746027ff6e2081b24e179ace8638 Mon Sep 17 00:00:00 2001 From: rootiest Date: Fri, 19 Jun 2026 02:23:35 -0400 Subject: [PATCH] docs(auto-pull): document auto-pull command, C2 behavior, and registry 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.) --- README.md | 2 +- docs/fish-config.index | 1 + docs/fish-config.md | 37 ++++++++++++++++++++++++++++++++++++- 3 files changed, 38 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 058de97..e6b58fd 100644 --- a/README.md +++ b/README.md @@ -258,7 +258,7 @@ If you'd rather set them by hand, each category is controlled by a universal var | 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_autoexec` | Startup side-effects: Fisher bootstrap, theme apply, `paru`/`yay` wrapper generation, auto venv activation, WakaTime hook | +| `__fish_config_op_autoexec` | Startup side-effects: Fisher bootstrap, theme apply, `paru`/`yay` wrapper generation, auto venv activation, WakaTime hook, auto-pull background fast-forward | | `__fish_config_op_overrides` | Vi mode, `exit`→`smart_exit`, `$PAGER`/`$MANPAGER`/`$CDPATH`, bang-bang history expansion, autopair, puffer, Starship prompt, theme colors | | `__fish_config_op_integrations` | Kitty/WezTerm window abbreviations, `done` notifications, `spwin`/`tab`/`split`, `hist`, `logs`, `upgrade`, WakaTime | | `__fish_config_op_logging` | Scrollback capture on exit, tmux `pipe-pane` pane logging, zellij `dump-screen` capture on exit, `paru`/`yay` AUR log wrappers, Kitty watcher capture (sentinel-file coordinated) | diff --git a/docs/fish-config.index b/docs/fish-config.index index 9660d6e..7f6d221 100644 --- a/docs/fish-config.index +++ b/docs/fish-config.index @@ -88,6 +88,7 @@ less=### less rawfish=### rawfish view=### view git=## 5.4 Git and Version Control +auto-pull=### auto-pull branch=### branch gi=### gi gitignore=### gi diff --git a/docs/fish-config.md b/docs/fish-config.md index 033f501..efa2b01 100644 --- a/docs/fish-config.md +++ b/docs/fish-config.md @@ -762,6 +762,30 @@ Add -i (interactive confirmation) to destructive commands: ## 5.4 Git and Version Control +### auto-pull + + Synopsis: auto-pull [list] + auto-pull add [PATH] + auto-pull remove + auto-pull status + + Manages the registry of repositories that are background fast-forwarded + when you enter them (see "Auto-pull fast-forward" under the C2 component + reference). The fish-config repo is always covered as a baseline. The + registry is machine-local at ~/.config/.user-dots/fish/auto-pull.list, one + absolute path per line, and is never committed. Registry management works + even when C2 auto-execution is disabled; only the background sync is gated. + + list Show registered repos (default) + add [PATH] Register PATH's git root (default: current repo) + remove Unregister by basename or exact path + status Show enabled/disabled state, repo count, list path + + cd ~/src/qmk_firmware; and auto-pull add + auto-pull add ~/work/api + auto-pull list + auto-pull remove qmk_firmware + ### branch Synopsis: branch @@ -1677,9 +1701,11 @@ __fish_config_op_autoexec prevents all of them. yay wrapper Every startup Writes ~/.local/bin/yay wrapper Python venv activation On every cd Sources .venv/bin/activate.fish WakaTime command hook On every command Reports to WakaTime API + Auto-pull fast-forward On entering a repo Background ff-only git pull When C2 is disabled: no Fisher install, no theme application, no paru/yay -wrapper generation, no automatic venv activation, and no WakaTime reporting. +wrapper generation, no automatic venv activation, no WakaTime reporting, and +no auto-pull (the PWD handler is never registered). The first-run completion marker (__fish_config_first_run_complete) is still set so the init does not re-run on subsequent shells. @@ -1687,6 +1713,15 @@ Python venv activation fires on every directory change. If a directory uses direnv (.envrc present), direnv takes priority and auto-venv is skipped for that directory. +Auto-pull fast-forwards opted-in repositories in the background when you cd +into them. The fish-config repo is always covered; other repos are added with +the `auto-pull` command (see its entry in the functions reference). It only +ever fast-forwards a clean repo whose branch has an upstream — never rebases, +merges, or overwrites work — so it is a no-op on dirty trees, divergent +branches, or repos without a remote. The handler fires once per repo entry +(not on every sub-directory cd). The registry is machine-local at +~/.config/.user-dots/fish/auto-pull.list and is never committed. + #### C3 — Key and Environment Overrides These change fundamental shell behavior: how keys work, which pager opens,