Theme
Aa
← man.tcos.us gopher root · man.tcos.us
lu: · ·
HEE-REPO-REFRESH(1)                HEE Tools                HEE-REPO-REFRESH(1)

NAME
       hee-repo-refresh  -  per-repo  health, pull, hygiene, prune and artifact
       regeneration

SYNOPSIS
              hee-repo-refresh MODE REPO_DIR
              hee-repo-refresh MODE [all|-all]
              hee-repo-refresh MODE -repo NAME[,NAME...]
              hee-repo-refresh regen [SCOPE] [--write]
              hee-repo-refresh help

DESCRIPTION
              The worker behind bootstrap.mk's health-all-repos and pull-all-repos
              targets. It lives in its own script, not inline in the Makefile, so the
              GNU parallel path and the sequential fallback call the same logic rather
              than two copies that can drift.

OPTIONS
              --write     apply the regeneration. Without it nothing is written.
              --json      hygiene only: one JSON object per repo.

ENVIRONMENT
              HEE_GIT_ROOT     where repos live. Default: $HOME/git
              HEE_GIT_TIMEOUT  seconds any single network git call may take before it is
                               reported as unanswered rather than waited on. Default: 45
              HEE_REGEN_TIMEOUT
                               seconds any single generator in `regen` may take before it
                               is reported as unanswered. Default: 300

EXIT STATUS
              0 completed   2 usage error

              regen reports in the Nagios vocabulary instead, because it has a real
              verdict to give:
                0 OK        every artifact current, or every stale one regenerated
                1 WARNING   something is stale (dry run), or was not written
                2 CRITICAL  a generator failed with its source reachable, or a write failed
                3 UNKNOWN   a source could not be reached -- NOT a pass

EXAMPLES
              hee repo-refresh health .
              hee repo-refresh regen --write
              hee repo-refresh refresh all

              Not marked "# ci": health reports a working tree's state against origin
              (which a runner's shallow, remote-less checkout does not have), and refresh
              and regen --write pull and rewrite generated files.

SEE ALSO
              hee-pve-health(1)   drift, which detects what regen acts on
              hee-gen-manpages(1), hee-gen-changelog(1)   two of the generators regen runs
              tooling/systemd/hee-regen.{service,timer}   the units that would schedule it;
                                                          installing them is an operator action

MODES
              health    report each repo's state in one line
              pull      fast-forward each repo
              hygiene   dirty-file and no-upstream-branch counts across ALL local
                        branches; prints nothing at all for a clean repo
              prune     delete local branches GitHub confirms are merged
              refresh   health, then pull, then the governance reminder -- the same
                        sequence as bootstrap.mk's refresh-all-repos
              regen     regenerate the generated artifacts these repos commit or
                        publish. DRY RUN unless --write
              gate      does this repo still pass hee-check as its own CI runs it,
                        against the human-execution-engine checkout beside it? The same
                        question .github/workflows/stable.yaml asks in CI before letting
                        `stable` advance -- asked locally, before pushing a tightening
                        that would turn other repos red with no commit to them

SCOPE
              A bare REPO_DIR is a filesystem path and is what bootstrap.mk passes
              internally; it skips the governance reminder, since that form is always
              one worker among many. `all`/`-all` and `-repo NAME,NAME` are the
              human-facing forms, and take repo NAMES (dotfiles, not a full path),
              resolved under ${HEE_GIT_ROOT:-$HOME/git}.

GATE
              Runs `hee-check all .` from INSIDE each repo, with human-execution-engine
              as a sibling checkout. Both details are load-bearing and were each measured
              wrong first: hee-check resolves cross-repo references by walking sibling
              checkouts with git, so an absolute-path invocation from elsewhere reports
              CRITICAL that the repo's own CI never sees.

              A repo's own HEE_*_SKIP exemptions are read out of its workflows and
              replayed, because "the repo declares the exemption, the checker never
              guesses". Reading them from the repo beats copying them: a copy drifts.

              A result is annotated when the tree is not a clean main at origin --
              [on BRANCH, not main], [N behind origin], [N uncommitted]. An unannotated
              line is the only one that is an answer about main.

              It judges the WORKING TREE, not origin. That is the point locally -- you
              want to know before you push -- but it means a result here can differ from
              CI. Measured 2026-09-07: dotfiles read 2 findings locally and 0 from a
              clean clone, purely from uncommitted work. When the two disagree, CI is
              right about main and this is right about your desk.

              Exit is 0 even when repos fail -- this reports, it does not gate. Read the
              per-repo lines.

REGEN
              `pull` brings in what other people wrote. `regen` brings in what the
              MACHINES say -- the artifacts in these repos that are generated and were
              being regenerated only when somebody remembered. Measured 2026-09-08: five
              generated artifacts, no crontab entry, no workflow, no timer touching any
              of them, and pve/network-map.md carrying a written admission that
              "regeneration is a habit, not a gate".

              DRY RUN IS THE DEFAULT, the same rule and the same reason as
              hee-gen-manpages and hee-release: a bare run reports what WOULD change and
              writes nothing (issue:464@human-execution-engine, where a documentation
              generator installed a pre-commit hook as a side effect of being run).

              IT NEVER COMMITS, and it never deploys. Regenerating is not landing.
              --write updates files in your working tree; opening the PR is yours. An
              artifact that is published rather than committed (view.lab's
              old-commits.html) is rendered and compared against what the host is really
              serving, and the deploy is named, never run.

              FAILS CLOSED. Each generator already answers "could you reach your source?"
              in its own exit code -- 3 is UNKNOWN in every hee tool -- so an artifact
              whose source is unreachable is reported UNKNOWN, counted, and named in a
              closing "source(s) not reached" line. It is never folded into the
              unchanged list, and the pass never returns a quietly shorter report. The
              cost of the alternative is measured: namespace-audit reported OK across 17
              repos for days while reading none of them (issue:423@fleet-ops).

              --write will not overwrite a destination that already has uncommitted
              changes; it says so and leaves it alone. Dirtiness is snapshotted once, at
              the start of the pass, because network-map.md holds two generated blocks
              and a per-write check would refuse the second one on dirtiness the pass
              itself had just created.

              The artifact registry is library/py/hee_regen -- a table, not a code path.

              `hee pve-health drift` already asked this question for the two pve
              artifacts and could only answer it. regen asks it for every declared
              artifact and, with --write, does something about the answer. The pve
              generators are reused, not reimplemented, so the two cannot disagree.

                                                            HEE-REPO-REFRESH(1)