Git Notes: o recurso mais legal e mais desprezado do Git (2022)

• Git notes é uma ferramenta poderosa que permite anexar metadados a commits e outros objetos
• Esse recurso permite armazenar informações complementares quando não é possível modificar a mensagem do commit
• Pode ser usado para guardar vários tipos de informação, como histórico de code review ou resultados de testes
• É possível até implementar um sistema distribuído de revisão de código, mas a usabilidade e o reconhecimento são baixos
• Com suporte limitado, como a desativação no GitHub, sua adoção no dia a dia é pequena

---

O que é Git notes

• Git notes é um recurso do git que permite anexar metadados a qualquer objeto rastreado pelo git (commit, blob, tree)
• Em geral, uma mensagem de commit registrada uma vez não pode ser alterada, mas com git notes é possível adicionar novas informações sem modificar o corpo do commit
• Por exemplo, é possível adicionar notes a um commit da seguinte forma
  • git notes add -m 'Acked-by: <이메일>'
• As notes aparecem junto no git log, em uma seção separada

Casos reais de uso

• No próprio projeto do git, git notes é usado para conectar commits a threads de discussão na mailing list
• Exemplos práticos de uso das notes incluem itens como
  • rastreamento de tempo de trabalho por commit ou branch
  • armazenamento de logs de code review e resultados de testes
  • projeto de um sistema de revisão de código totalmente distribuído

Armazenamento de revisões de código e resultados de testes

• Está aumentando o número de casos em que code forges e sistemas de revisão oferecem suporte para armazenar metadados de revisão de código offline, ou seja, no próprio git
• O plugin reviewnotes do Gerrit mostra no git log, por meio de notes, quem fez a revisão e quais testes foram executados
  • O usuário pode verificar localmente o histórico de revisão de código sem precisar abrir o navegador separadamente

Sistema distribuído de revisão de código

• Há casos como o git-appraise, desenvolvido no Google, que realiza revisão de código distribuída usando git notes
• O git-appraise registra em git notes todo o processo, incluindo solicitação de revisão de código, comentários sobre alterações e merge após a revisão, e funciona de forma independente de serviços online de hospedagem de código
• Toda a colaboração pode ser feita em ambiente local, e ele ainda oferece uma interface web

Baixa usabilidade e reconhecimento

• Git notes quase não é usado porque sua interface é desconfortável e pouco intuitiva para usuários em geral
• Como o GitHub deixou de exibir commit notes depois de 2014, as oportunidades de uso diminuíram ainda mais
• Embora o gerenciamento de notes em commits possa ser facilitado um pouco mais com configurações do git, para anexar notes a objetos blob ou tree é necessário entender melhor a estrutura interna do git (plumbing)
• Como resultado, git notes continua sendo um recurso de nicho, com reconhecimento muito baixo

Independência de forges abertas

• O próprio git pode oferecer suporte a controle de versão distribuído e revisão de código, mas muito do valor adicional, como o histórico de revisões, tende a ficar dependente de serviços de hospedagem como o GitHub
• Ao aproveitar o recurso Git notes, abre-se o caminho para armazenar e distribuir de forma descentralizada não só a evolução do código em si, mas também todo o histórico do projeto
• Isso tem um significado importante para um ecossistema de desenvolvimento verdadeiramente distribuído e para a preservação dos registros

[GN⁺]

Opiniões no Hacker News

• Compartilhando a informação de que existe um recurso menos conhecido chamado Git trailers; os trailers permitem inserir metadados em formato chave-valor ao criar um commit. Eles são usados, por exemplo, para anexar Change-Id no Gerrit. Link do artigo relacionado

  • Compartilhando que o PostgreSQL tem um recurso parecido chamado COMMENT; o COMMENT permite adicionar texto a objetos do banco de dados. Seria interessante se o PostgreSQL também oferecesse edição de metadados estruturados em formato chave-valor. Link da documentação relacionada

  • Compartilhando a experiência de usar git notes ao trabalhar com upstream open source para marcar commits cujos testes unitários foram concluídos; isso era útil ao organizar a branch com git rebase -i, mas hoje trailers parecem uma abordagem melhor. Se algo como Change-Id viesse no próprio Git, as ferramentas poderiam entender isso melhor. Distinguir commits pela mensagem de commit é sutilmente frágil; IDs de commit são bons pela unicidade, mas perdem utilidade como identificador quando a mesma mudança é movida para cima de outro commit. Edição: como trailers fazem parte do commit, eles não substituem completamente notes.

  • Recentemente descobri que o GitHub usa um trailer separado em vez de [skip ci], provavelmente para facilitar a extração da informação da mensagem de commit. Não está claro por que o GitHub exige apenas o último trailer; talvez seja por causa do processamento com regex. Link da documentação relacionada

  • Estou conhecendo o recurso de trailers agora; como fã de Conventional Commits, parece que trailers seriam melhores para adicionar esse tipo de metadado. Fiquei curioso se adicionar manualmente na mensagem de commit e usar a flag --trailer é funcionalmente a mesma coisa.

  • Naturalmente dá vontade de integrar isso com um sistema de issue tracking, mas colocar esse tipo de coisa em trailers parece ineficiente porque fica distante demais do issue tracker. Issue trackers têm o problema de seguir tendências e receber vários recursos tarde demais. Também é incômoda a regra de ter que usar obrigatoriamente como título do PR o nome da branch derivado do ticket. Eu queria ligar commits e issues com outros metadados para tornar o título do PR mais significativo, mas isso não é algo fácil de mudar, então vira assunto para reclamar na internet.

• Compartilhando que o Forgejo passou a oferecer suporte a trailers a partir da versão 10, lançada em janeiro deste ano. Notas de lançamento Pull request

• Curiosidade sobre a interação entre git notes e recursos de reescrita de histórico (amend, rebase etc.); como notes ficam ligados a IDs de commit/tree/blob, fica a dúvida se eles são copiados ou desaparecem quando o commit é substituído por um novo. Também há curiosidade sobre o que acontece ao juntar vários commits com interactive rebase. Foi compartilhada a percepção de que notes ficarem presos ao "conteúdo" de arquivos/diretórios foge da expectativa; por exemplo, se você anexa uma note ao blob da string "Hello world!", isso vale para todos os arquivos com o mesmo conteúdo? E se o arquivo mudar, as notes se perdem?

  • Em git rebase etc., a cópia de notes pode ser configurada para acontecer por padrão; veja a opção notes.rewrite no git-config(1).

• No trabalho atual, usamos git notes de forma ativa para registrar histórico interno de code review sem complicar a mensagem de commit nem criar PR para toda mudança. Deixamos contexto na branch, como a que ticket cada commit está mapeado, restrições de infraestrutura e, no caso de correções, links para threads de incidente. Guardar essa informação no repositório facilita entender por que uma linha mudou sem precisar procurar em Slack ou Jira. Em escala, isso pode reduzir claramente a necessidade de UI de plataformas. A opinião é que reproducibility é necessária não só para builds, mas também para a "intent".

  • Fiquei curioso se esse tipo de informação não seria melhor na mensagem de commit, ou se a intenção é também ligar direções futuras, como "este commit causou o bug #123".

• git notes só é realmente útil quando informação adicional passa a ser necessária depois do commit. Exemplos como Acked-By e links para discussões em mailing list já são informações conhecidas no momento do commit, então poderiam ir na mensagem de commit. O verdadeiro ponto forte de uma git note, na visão expressa, é anexar explicações adicionais depois, como em commits que mais tarde foram revertidos.

  • Muitas vezes a mensagem de commit diz com orgulho que corrigiu um bug, mas na prática não corrigiu; isso acaba gerando bugs em cascata, e colegas frequentemente ignoram a intenção original e passam por cima. Depois de passar por clientes irritados e por recorrência de bugs, veio a sensação de que é preciso mais cautela ao chamar algo de bug fix. Às vezes uma mudança corrige vários bugs de uma vez, ou abre espaço para melhoria de desempenho e novos recursos por meio de refatoração.

  • Acked-By, review e discussões inevitavelmente continuam depois do commit; não dá para saber tudo isso no momento em que ele é feito. Em casos de revert de commit, por outro lado, faz mais sentido adicionar isso à mensagem de commit, já que o recurso de blame mostra a alteração mais recente e naturalmente ajuda a rastrear commits revertidos.

  • Em muitos casos, a discussão continua mesmo depois do commit.

• Parece um ponto interessante para explorar o recurso de notes com o objetivo de fornecer contexto adicional a agentes de código.

• Isso não é falta de conhecimento, e sim um problema de UI; se a UI do GitHub mostrasse notes direito, elas provavelmente seriam usadas muito mais.

  • Tomara que o GitHub passe a oferecer suporte a notes.

• O git tem muitas funcionalidades "mais legais e pouco amadas", como bisect, pickaxe, reflog, range-diff, archive e annotated tags, mas a maioria das pessoas o trata apenas como se fosse um Google Drive e por isso não usa esses recursos.

  • git notes acaba parecendo redundante, já que o contexto não técnico de features, roadmap etc. costuma ser acompanhado em uma ferramenta separada de gestão de projetos, como Jira; pela filosofia Unix, cada coisa deveria focar no seu papel.

  • Nunca tinha ouvido falar de pickaxe, então foi uma surpresa; talvez não seja bom ficar confiante demais.

  • Muitas dessas funcionalidades ornamentais na prática não são tão úteis assim; há quem as veja como truques periféricos em torno do essencial.

• A opinião é que git notes não é exatamente um recurso "legal" e pouco amado, mas algo útil apenas em situações bem específicas e limitadas. Há vantagens em colocar toda a informação realmente necessária na mensagem de commit e referenciá-la a partir de outros sistemas, como JIRA. Sistemas como JIRA também servem como canal de comunicação com analistas de negócios e equipe de suporte, que não são desenvolvedores; faz sentido que pessoas não desenvolvedoras não tenham acesso ao repositório e ao código. Em contextos com vários serviços e repositórios ao mesmo tempo, referenciar features por meio de notes seria irrealista; a integração com sistemas externos seria necessária.

  • Foi apontado que é ineficiente analistas de negócios não terem acesso ao código ou ao repositório, já que às vezes bastaria olhar uma única linha para entender algo, mas acabam perguntando toda vez. Também foi mencionada a realidade de que existem analistas tecnicamente capacitados, mas a cultura não muda com facilidade.

• A pessoa conheceu notes pela man page por volta de 2020, mas como notes se aplicam basicamente só ao repositório local, nunca teve experiência real de uso. Para uso em equipe, seria preciso configurar push/fetch separadamente e decidir adotar isso coletivamente, mas o time dela não seguiu por esse caminho.