Commits Triangle
Um assunto se parece com isto:
<área><comportamento ou intenção>[modificador] <ticket> (<escopo>): <resumo>
🧩👔 #412 (servidor): permitir recurso em até 30 dias da recusa
🎨💄 — (tokens): pegar os novos tons do Figma
Os emojis são os primeiros caracteres da linha, sem nada ao redor. O último exemplo é um commit feito por um job: não tem ticket, então carrega um travessão.
O vocabulário é grande de propósito, e você não precisa decorá-lo. O
comando gitmoji o entrega em pequenas partes. Leia apenas a parte que você precisa.
O comando
Use o comando gitmoji. Se não estiver no PATH, leia references/vocabulary.txt na pasta desta habilidade
para o vocabulário completo, e informe à pessoa que o comando está faltando.
| Quando | Execute |
|---|---|
| Você precisa da lista de áreas | gitmoji guide areas |
| Você conhece a área | gitmoji guide 🧩 (qualquer emoji ou nome de área) |
| Nada no guia da área se encaixa | gitmoji guide groups, depois um grupo: gitmoji guide "reparo" |
| Duas entradas parecem se encaixar | gitmoji guide 🛡️, ou o grupo: gitmoji guide "proteção" |
| O trabalho é experimental, paliativo ou quebra | gitmoji guide modifiers |
| Você precisa dos nomes de escopo | gitmoji guide scopes |
| Você está prestes a escrever o resumo ou o corpo | gitmoji guide message |
Antes de git commit | gitmoji staged, depois gitmoji check -m '<assunto>' para a primeira linha, ou gitmoji check <arquivo> para uma mensagem inteira |
Você digitou shortcodes como :jigsaw::necktie: | Nada: o hook escreve os emojis para você |
| Você está desfazendo um commit | git revert <commit>; a primeira linha do git permanece como está |
| O hook recusou um assunto | Leia sua mensagem; ela nomeia a correção |
| Você quer revisar os commits do seu branch antes do merge | gitmoji history trunk..HEAD (o branch onde vai fazer merge, depois o seu) |
| O hook diz que o repositório adotou outra versão | Leia o que mudou no endereço que ele fornece e informe ao usuário antes de alterar as configurações |
Antes de escrever código: planeje os commits
Leia o ticket e escreva os assuntos que você espera fazer, como uma lista. Cada um é uma
decisão que um revisor poderia aceitar por si só, e cada um é algo que o ticket pede.
O escopo de cada um é o pacote que possui a decisão (gitmoji guide scopes).
Estes são prompts, não uma pilha a preencher. Planeje um commit apenas onde o ticket dá uma resposta à pergunta:
- O que o negócio decide (
👔), e o que acontece ao longo do tempo (⛓️)? - O que é recusado antes que uma etapa seja tentada (
🛡️)? Quando uma etapa falha, como ela se recupera, qual código de erro reporta, e o que as pessoas são informadas (🥅)? - Que formato é acordado entre as partes (
🏷️), e o que é armazenado (💾)? - O que os usuários veem e fazem, e em qual commit eles ganham isso pela primeira vez (
✨)? - Como saberemos que um usuário consegue passar por isso no produto real (
✅, seu próprio commit, adicionado assim que o produto puder ser executado dessa forma)?
Quando o percurso ainda não pode ser executado, entregue a funcionalidade e diga no ticket que seu ✅
está pendente. Não coloque ✅ em uma verificação menor para preencher a lacuna; isso é ☑️.
Verifique se já existe um proprietário antes de planejar um novo endpoint, armazenamento ou política. Se uma decisão de produto estiver faltando e puder mudar o que é entregue, anote a pergunta e pergunte. Não a resolva dentro de um commit.
Uma funcionalidade que é uma decisão, com seu único chamador e as verificações que precisa, é um commit. Planeje mais linhas apenas onde o ticket contém mais de uma decisão que um revisor poderia tomar separadamente. Uma linha que o ticket nunca pediu é detalhamento excessivo.
Antes de cada commit: quatro perguntas
- Qual área a mudança faz parte, ou sobre o que é? Um teste, um documento e um playground assumem a área da coisa sobre a qual são.
- O que é diferente agora, ou o que você fez? Se o commit muda o que é prometido, nomeie o comportamento (um substantivo). Caso contrário, nomeie a intenção (um verbo).
- O trabalho não está resolvido? Apenas então adicione um terceiro emoji:
🧪experimental,🚧paliativo,💥consumidores devem se adaptar. Um experimental mantém🧪em cada commit até🏁(mantido) ou⚰️(descartado), e nada resolvido pode depender dele antes disso. Construir a direção que um ticket escolheu não é experimental. - Qual ticket? Use o formato de ticket do repositório. Apenas um job escreve
—.
Em seguida, execute gitmoji check -m '<assunto>'.
Antes de preparar (stage), leia a mudança como alguém que não estava presente. Onde a razão não pode ser vista no código, escreva um comentário ao lado do código: por que é do jeito que é, o que não deve ser mudado, de onde vem um valor. Diga o porquê, não o que a linha faz. Um comentário custa quase nada e salva o próximo leitor, uma pessoa, um júnior ou um agente sem seu contexto, de ter que adivinhar.
Quando um par não se encaixa
Esse é o sinal para olhar novamente, não para escolher a tag mais próxima.
- Quando dois rótulos se encaixam, nomeie o que o revisor poderia aceitar agora e o que poderia
adiar. Separe quando essas duas decisões podem diferir e o que é mantido ainda funciona por
si só. Prepare por caminho ou por pedaço (hunk) (
git add -p). - Mantenha o único chamador, sua conexão (wiring) e as verificações de recusa de que precisa juntos quando nenhum deles tem uma promessa própria. Etiquete o commit pelo seu ponto principal; o resto acompanha.
gitmoji stagedrelata dois escopos: faça a mesma pergunta. Se a mudança só faz sentido como um todo, como uma forma espelhada em duas linguagens, mantenha-a junto e nomeie o pacote que possui a decisão.- Partes que são forçadas pela mudança principal acompanham: seus tipos, seu teste, uma história, um lockfile.
Cada commit ainda deve compilar e passar por si só. Se dividir quebrasse isso, mantenha as partes forçadas juntas e diga isso no corpo.
Escrevendo
- Resumo: o que o sistema faz agora, nas palavras do domínio, começando com um verbo
em letra minúscula. A primeira linha inteira cabe em 140 caracteres, emojis, ticket e escopo
incluídos, e quanto mais curto, melhor;
gitmoji check -m '<assunto>'conta para você antes de commitar. Nenhum nome de arquivo, nenhum número de ticket, nenhum "como". - Descrição: todo commit que você escreve tem uma, e o hook recusa um commit sem
ela. Apenas um marcador (
🔖,🔺), um commit feito por um job e uma mensagem que o git escreveu não precisam de nenhuma. Abaixo da primeira linha, uma linha vazia, depois por que a mudança foi feita: a razão, por que deste jeito e não o óbvio, ou o valor que você escolheu. Uma ou duas linhas geralmente são suficientes; seis são o máximo. Mantenha referências a tickets dentro da frase (por exemplo, "Veja #42 para a decisão"). O Git pode remover uma linha começando com#42quando alguém edita o commit. Não reconte o diff, liste arquivos ou descreva seu processo. - Emojis, não shortcodes. Apenas os caracteres são commitados.
Quem escreveu
Nunca se adicione como autor ou co-autor. Nenhuma linha Co-Authored-By:, nenhuma identidade
de agente em git config user.* ou --author. O autor é a pessoa responsável, e
o hook recusa um agente lá. Algumas ferramentas adicionam uma linha de co-autor para si mesmas sem
serem solicitadas; quando o hook recusar um commit por isso, remova a linha e commite novamente.
Em vez disso, termine o corpo com uma linha vazia e uma assinatura que diz o que entrou no commit:
_
example-model (alto), editor
Claude Code (sessão-exemplo)
Sub-agentes: 2 × example-helper (médio)
Time: revisor, testador
Pesquisa: 3 pesquisas, 12 páginas
As três primeiras linhas estão sempre lá. As três últimas aparecem apenas quando se aplicam.
Quando o commit é feito, o hook substitui o sublinhado por △ e, entre crases,
a versão do vocabulário contra a qual a mensagem foi verificada, então uma assinatura armazenada se parece com isto:
△ `1.2.3`
example-model (alto), editor
Claude Code (sessão-exemplo)
Escreva o sublinhado; nunca escreva a linha △ você mesmo. O hook fecha toda mensagem
com ele, também a de uma pessoa, que então tem aquela única linha e nenhuma assinatura.
gitmoji history a lê para dizer quais commits estão em qual versão.
Projetos podem definir signature = "agents" em [rules] para exigir as linhas de modelo e harness quando uma sessão de agente suportada executa o hook de commit. Um humano pode commitar com a descrição comum. Marcadores de release e mensagens geradas pelo Git mantêm suas isenções existentes.
| Linha | O que significa |
|---|---|
_ | A assinatura começa aqui. O hook a transforma em △ `<versão>` . |
| linha do modelo | O modelo e seu esforço. Após uma vírgula, seu nome, apenas se uma pessoa lhe deu um. |
| linha do harness | O harness e, entre parênteses, o id da sessão, se houver. |
Sub-agentes: | Quantos subagentes fizeram parte do trabalho deste commit, por modelo e esforço. |
Time: | Os outros agentes com quem você trocou mensagens para este commit. |
Pesquisa: | Pesquisas na web, páginas lidas e consultas a documentação para este commit. |
Não escreva nada disso de memória. Execute o script para seu harness em scripts/
nesta pasta da habilidade e cole o que ele imprime. O caminho é relativo à pasta onde este
arquivo está, onde quer que a habilidade esteja instalada:
python3 scripts/claude-code.py
No Claude Code, essa pasta é ${CLAUDE_SKILL_DIR}. O script lê o registro do próprio
harness da sessão. Se seu harness não tem script lá, scripts/README.md diz como
trabalhar um uma vez e adicioná-lo. Onde nenhum registro pode ser encontrado, o script imprime
unknown. Um repositório pode pedir para você omitir uma linha, como o id da sessão; suas próprias
instruções dizem isso.
Se a sessão abranger várias tarefas ou repositórios, verifique as linhas opcionais de atividade em relação a este commit. Mantenha apenas as contribuições que você pode atribuir a ele.
Linhas que o corpo pode carregar
🩹precisa deLimitação: <o que a dependência não pode fazer>.📥precisa deFonte: <a execução, ferramenta ou sistema de onde veio>.🏁e⚰️dizem o que o decidiu.🐛pode nomear a causa:Quebrado-por: <sha>.
Ao atualizar o Gitmoji
O CLI, a habilidade e o vocabulário compartilham um número de release. O hook avisa quando as configurações do repositório nomeiam outra versão diferente daquela que o comando
fala. Informe o usuário e leia o que mudou no endereço que o aviso fornece. Quando o
usuário quiser a nova versão, configure-a em [vocabulary] nas configurações e commite apenas
isso, com a versão entre crases:
🔺 gitmoji `<versão>`: <o que muda para este repositório>
Não reescreva um histórico que já foi compartilhado a menos que o usuário peça: commits
feitos sob regras anteriores podem permanecer como estão. gitmoji history --unmigrated mostra
quais deles não passariam hoje. Execute gitmoji init após alterar o pin para atualizar a habilidade instalada e os workflows gerenciados.
Fazendo merge de pull requests e atualizando histórico
Ative o workflow de título de PR e selecione Pull request title and description como a mensagem de merge padrão. Escreva o título humano. O Gitmoji mantém seu prefixo de emoji à medida que os commits mudam. Use Create a merge commit com a mensagem sugerida. O GitHub preserva os commits autorados e anexa o número do PR integrado.
Para um histórico existente, use o guia de atualização
e o script instalado scripts/gitmoji-upgrade-history.py. Inspecione a simulação (dry run)
antes de criar um candidato local. Links exigem evidência de qual PR foi integrado.
Uma substituição em branch compartilhado é uma decisão separada para os proprietários do repositório.
Mensagens que o Git escreve
Um merge pode ter qualquer título. O hook preserva o arquivo de mensagem do Git durante um
merge pendente, e gitmoji history reconhece um merge armazenado por seus múltiplos pais.
Um check -m apenas textual tem apenas o assunto para trabalhar. Ele reconhece os
cabeçalhos comuns de merge de branch, tag e commit do Git, cabeçalhos de merge de pull request do GitHub,
legendas numeradas Merge #N, assuntos de revert e reapply do Git citados,
legendas numeradas Revert #N e Reapply #N com um título, o cabeçalho de log squash
padrão do Git e os prefixos de autosquash fixup! , squash! e amend! .
Um squash merge com um título de PR personalizado produz um commit comum de um pai. Cherry-picks e rebases também podem carregar assuntos comuns adiante. Verifique esses como outros commits autorados. Um número de PR por si só não identifica um merge.
Durante a adoção, um projeto pode definir [rules] → untagged = "warn" em
gitmoji.toml para aceitar assuntos simples e sinalizá-los para revisão. O padrão
é "error". Com "off", a tag faltante é aceita silenciosamente. Outras verificações
ainda se aplicam. Use gitmoji history trunk..HEAD no seu branch para encontrar assuntos
a reformular antes de compartilhar. O histórico sempre verifica assuntos sem tag estritamente.
Quando nada se encaixa
Não force uma entrada. Use a mais honesta disponível, adicione uma linha no corpo
Falta: <o que você queria dizer> e informe o usuário. Falhas são como o vocabulário é corrigido.