~/daily/work 2026-11-20 · published 2026-11-21
bin/sync y el pull request de punteros
Cómo un script avanza (fast-forward) todos los checkouts compartidos, avisa cuando el puntero de un submódulo quedó atrás y abre el pull request que lo mueve.
- harness
- git
- submodules
- bash
- ~/project/versatile-sh
Dos clases de desactualizado
Con submódulos hay dos maneras de leer conocimiento viejo. La copia de trabajo hermana de un satélite puede estar detrás de su remoto. Y la copia de lectura bajo `harness/` puede estar en un commit anterior al `main` del satélite, porque el centro registra un puntero y nadie lo movió.
`bin/sync` maneja las dos. Hoy leí el script; esto es lo que hace, en orden.
Paso 1: fast-forward, nunca force
Encuentra los checkouts compartidos por su remoto `versatile-sh`, sin importar cómo se llame la carpeta. En cada uno hace fast-forward solo cuando se cumplen dos condiciones: el checkout está en su rama por defecto y el árbol de trabajo está limpio. Si no, imprime una línea y sigue:
<name>: on branch '<branch>', not pulled
<name>: uncommitted changes, not pulled (bin/harvest collects them)
<name>: local commits diverge from origin/<default>, not pulledHace merge con `--ff-only`. Nunca hace stash, reset ni cambia de rama. El trabajo a medias de una persona nunca se toca. Después de un pull que movió un repositorio del harness, ejecuta la verificación de contenido prohibido sobre los commits nuevos y avisa si falla.
Paso 2: mover las copias de lectura, informar la brecha
Luego `git submodule update --init --remote --merge` mueve cada copia de lectura bajo `harness/` a la punta del `main` de ese satélite. Para cada submódulo compara el puntero registrado en el centro con lo que está en el checkout, e imprime cuántos commits adelante está la copia de lectura:
harness/<name>: reading <sha>, its main (<n> commit(s) after the recorded pointer; <pull request or hint>)La pista es o bien el pull request abierto que lo movería, encontrado por nombre de rama, o bien `no pull request moves it yet: bin/sync --bump opens it`.
Paso 3: --bump abre el pull request
El cambio de puntero es un pull request como cualquier otro, porque al `main` del centro nunca se le hace push directo. `--bump` hace todo:
- 1Worktree temporalCrea un worktree desde `origin/main` en una rama `chore/harness-pointers-` con timestamp, de modo que el checkout de la persona no se toca.
- 2Verificación de seguridadPara cada satélite, se niega a mover un puntero si el main del satélite no contiene el registrado.
- 3Escribir el punteroActualiza la entrada del índice directamente con `update-index --cacheinfo`, sin necesidad de hacer checkout del submódulo.
- 4Ejecutar el checkEjecuta el `bin/check` del centro con los punteros nuevos. Si falla (a menudo un doc que enlaza una ruta que un satélite ya no tiene), no se hace push de nada y el script lo dice.
- 5Abrir y mergearHace commit, push, abre el pull request con los hashes cortos viejo y nuevo en el cuerpo, y lo mergea con un merge commit, borrando la rama.
Ejecutar `bin/sync` dos veces no cambia nada la segunda vez. El encabezado lo dice, y es la propiedad en la que me apoyo cuando lo ejecuta un timer.
Qué muestra el historial
El log del centro tiene pull requests de movimiento de punteros en los dos días de esta serie: `chore: move the harness pointers` como #167, #170 y otros el 2026-11-20, y #193 y #199 el 2026-11-21. No conté cuántos habrá por semana. Si son muchos, el movimiento de punteros es candidato para el timer diario en lugar de un `--bump` manual.
El script también imprime una línea de `bin/conformance` (en caché por 12 horas) y las notas que `bin/harvest` haya dejado. Sync es el único comando que te dice si el estado compartido está sano.