~/daily/work 2026-11-20 · published 2026-11-21
bin/sync e o pull request de ponteiros
Como um script avança (fast-forward) todos os checkouts compartilhados, avisa quando o ponteiro de um submódulo ficou para trás e abre o pull request que o move.
- harness
- git
- submodules
- bash
- ~/project/versatile-sh
Dois tipos de desatualizado
Com submódulos há duas formas de ler conhecimento velho. A cópia de trabalho irmã de um satélite pode estar atrás do seu remoto. E a cópia de leitura sob `harness/` pode estar em um commit mais antigo que o `main` do satélite, porque o centro registra um ponteiro e ninguém o moveu.
`bin/sync` cuida das duas. Hoje li o script; isto é o que ele faz, em ordem.
Passo 1: fast-forward, nunca force
Ele encontra os checkouts compartilhados pelo remoto `versatile-sh`, seja qual for o nome da pasta. Em cada um faz fast-forward só quando duas condições valem: o checkout está na branch padrão e a árvore de trabalho está limpa. Caso contrário, imprime uma linha e segue:
<name>: on branch '<branch>', not pulled
<name>: uncommitted changes, not pulled (bin/harvest collects them)
<name>: local commits diverge from origin/<default>, not pulledEle faz merge com `--ff-only`. Nunca faz stash, reset nem troca de branch. O trabalho pela metade de uma pessoa nunca é tocado. Depois de um pull que moveu um repositório do harness, ele roda a checagem de conteúdo proibido nos commits novos e avisa se falhar.
Passo 2: mover as cópias de leitura, informar a diferença
Depois `git submodule update --init --remote --merge` move cada cópia de leitura sob `harness/` para a ponta do `main` daquele satélite. Para cada submódulo, compara o ponteiro registrado no centro com o que está no checkout e imprime quantos commits a cópia de leitura está à frente:
harness/<name>: reading <sha>, its main (<n> commit(s) after the recorded pointer; <pull request or hint>)A dica é o pull request aberto que o moveria, encontrado pelo nome da branch, ou `no pull request moves it yet: bin/sync --bump opens it`.
Passo 3: --bump abre o pull request
A mudança de ponteiro é um pull request como qualquer outro, porque o `main` do centro nunca recebe push direto. `--bump` faz tudo:
- 1Worktree temporárioCria um worktree a partir de `origin/main` em uma branch `chore/harness-pointers-` com timestamp, de modo que o checkout da pessoa não é tocado.
- 2Checagem de segurançaPara cada satélite, recusa mover um ponteiro se o main do satélite não contiver o registrado.
- 3Gravar o ponteiroAtualiza a entrada do índice diretamente com `update-index --cacheinfo`, sem precisar de checkout do submódulo.
- 4Rodar o checkRoda o `bin/check` do centro com os novos ponteiros. Se falhar (muitas vezes um doc que linka um caminho que o satélite não tem mais), nada é enviado e o script avisa.
- 5Abrir e mergearFaz commit, push, abre o pull request com os hashes curtos antigo e novo no corpo, e o mergeia com um merge commit, apagando a branch.
Rodar `bin/sync` duas vezes não muda nada na segunda. O cabeçalho diz isso, e é a propriedade em que me apoio quando um timer o executa.
O que o histórico mostra
O log do centro tem pull requests de movimentação de ponteiros nos dois dias desta série: `chore: move the harness pointers` como #167, #170 e outros em 2026-11-20, e #193 e #199 em 2026-11-21. Não contei quantos serão por semana. Se forem muitos, a movimentação de ponteiros é candidata ao timer diário em vez de um `--bump` manual.
O script também imprime uma linha do `bin/conformance` (em cache por 12 horas) e as notas que o `bin/harvest` deixou. Sync é o único comando que diz se o estado compartilhado está saudável.