gitmoji

Habilidade de codificação. Escreva commits git no formato Gitmoji Triangle (par de emojis, ticket, escopo, resumo) e divida o trabalho em um commit por decisão. Use ao planejar commits para um ticket, antes de cada `git commit`, quando o hook `gitmoji commit-msg` recusar um assunto, ao fazer merge de um pull request e ao revisar mensagens geradas em histórico antigo.

O que é gitmoji?

Gitmoji é uma habilidade para agentes de IA que padroniza commits Git em um formato rígido, porém expressivo, chamado "Triangle Commits". Cada linha de assunto segue a estrutura `<emoji><emoji>[modifier] <ticket> (<scope>): <summary>`, onde os emojis codificam a área e o comportamento/intenção da mudança, o ticket referencia a tarefa, e o escopo delimita o pacote afetado. Esta habilidade resolve o problema de commits ambíguos ou mal estruturados, fornecendo um vocabulário controlado via comando `gitmoji` e um hook de commit-msg que valida e recusa assuntos fora do padrão. É suportada por ferramentas como Claude Code, Cursor e Codex, e seu fluxo orienta o agente a planejar commits antes de escrever código (um commit por decisão do ticket), responder a quatro perguntas antes de cada commit, e gerar assinaturas detalhadas no corpo da mensagem, incluindo modelo de IA, sessão e contribuições de subagentes. A habilidade também gerencia versionamento do vocabulário, migração de histórico existente e integração com pull requests, garantindo que cada commit seja independente, compilável e rastreável.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/D1no/gitmoji/tree/HEAD/skills/gitmoji

Installed? Explore more Programação e Desenvolvimento skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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.

QuandoExecute
Você precisa da lista de áreasgitmoji guide areas
Você conhece a áreagitmoji guide 🧩 (qualquer emoji ou nome de área)
Nada no guia da área se encaixagitmoji guide groups, depois um grupo: gitmoji guide "reparo"
Duas entradas parecem se encaixargitmoji guide 🛡️, ou o grupo: gitmoji guide "proteção"
O trabalho é experimental, paliativo ou quebragitmoji guide modifiers
Você precisa dos nomes de escopogitmoji guide scopes
Você está prestes a escrever o resumo ou o corpogitmoji guide message
Antes de git commitgitmoji 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 commitgit revert <commit>; a primeira linha do git permanece como está
O hook recusou um assuntoLeia sua mensagem; ela nomeia a correção
Você quer revisar os commits do seu branch antes do mergegitmoji history trunk..HEAD (o branch onde vai fazer merge, depois o seu)
O hook diz que o repositório adotou outra versãoLeia 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

  1. 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.
  2. 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).
  3. 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.
  4. 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 staged relata 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 #42 quando 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.

LinhaO que significa
_A assinatura começa aqui. O hook a transforma em △ `<versão>` .
linha do modeloO modelo e seu esforço. Após uma vírgula, seu nome, apenas se uma pessoa lhe deu um.
linha do harnessO 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 de Limitação: <o que a dependência não pode fazer>.
  • 📥 precisa de Fonte: <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.

Habilidades Relacionadas