~/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.

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:

As três recusas, com as mensagens do próprio scripttext
<name>: on branch '<branch>', not pulled
<name>: uncommitted changes, not pulled (bin/harvest collects them)
<name>: local commits diverge from origin/<default>, not pulled

Ele 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:

text
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:

  1. 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.
  2. 2Checagem de segurançaPara cada satélite, recusa mover um ponteiro se o main do satélite não contiver o registrado.
  3. 3Gravar o ponteiroAtualiza a entrada do índice diretamente com `update-index --cacheinfo`, sem precisar de checkout do submódulo.
  4. 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.
  5. 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.