~/daily/work 2026-11-20 · published 2026-11-21

bin/sync and the pointer pull request

How one script fast-forwards every shared checkout, reports a submodule pointer that fell behind, and opens the pull request that moves it.

Two kinds of stale

With submodules there are two ways to read old knowledge. The sibling working copy of a satellite can be behind its remote. And the read copy under `harness/` can be at a commit older than the satellite's `main`, because the center records a pointer and nobody moved it.

`bin/sync` handles both. I read through the script today; this is what it does, in order.

Step 1: fast-forward, never force

It finds the shared checkouts by their `versatile-sh` remote, whatever the folder is called. For each one it fast-forwards only when two conditions hold: the checkout is on its default branch and the working tree is clean. Otherwise it prints one line and moves on:

The three refusals, from the script's own messagestext
<name>: on branch '<branch>', not pulled
<name>: uncommitted changes, not pulled (bin/harvest collects them)
<name>: local commits diverge from origin/<default>, not pulled

It merges with `--ff-only`. It never stashes, resets or switches branch. A person's half-finished work is never touched. After a pull that moved a harness repository, it runs the forbidden-content check on the new commits and says so if it fails.

Step 2: move the read copies, report the gap

Then `git submodule update --init --remote --merge` moves each read copy under `harness/` to the tip of that satellite's `main`. For every submodule it compares the pointer recorded in the center with what is checked out, and prints how many commits the read copy is ahead:

text
harness/<name>: reading <sha>, its main (<n> commit(s) after the recorded pointer; <pull request or hint>)

The hint is either the open pull request that would move it, found by branch name, or `no pull request moves it yet: bin/sync --bump opens it`.

Step 3: --bump opens the pull request

The pointer change is a pull request like any other, because the center's `main` is never pushed to directly. `--bump` does all of it:

  1. 1Temporary worktreeCreates a worktree from `origin/main` on a timestamped `chore/harness-pointers-` branch, so the person's checkout is untouched.
  2. 2Safety checkFor each satellite, refuses to move a pointer if the satellite's main does not contain the recorded one.
  3. 3Write the pointerUpdates the index entry directly with `update-index --cacheinfo`, no checkout of the submodule needed.
  4. 4Run the checkRuns the center's `bin/check` with the new pointers. If it fails (often a doc that links to a path a satellite no longer has), nothing is pushed and the script says so.
  5. 5Open and mergeCommits, pushes, opens the pull request with the old and new short hashes in the body, and merges it with a merge commit, deleting the branch.

Running `bin/sync` twice changes nothing the second time. The header says so, and it is the property I rely on when a timer runs it.

What the history shows

The center's log has pointer-move pull requests on both days of this series: `chore: move the harness pointers` as #167, #170 and others on 2026-11-20, and #193 and #199 on 2026-11-21. I did not count how many a week they will be. If it is high, the pointer move is a candidate for the daily timer instead of a manual `--bump`.

The script also prints one line from `bin/conformance` (cached for 12 hours) and any notes `bin/harvest` left behind. Sync is the one command that tells you whether the shared state is healthy.