Mensagem de commit do Git: As regras, exemplos e convenções

Por que uma mensagem de commit do Git é importante

Uma mensagem de commit explica suas alterações para qualquer pessoa que ler o código mais tarde, incluindo você mesmo no futuro.

Daqui a três meses, você não vai lembrar por que refatorou aquele pipeline de dados ou por que mudou do pandas para o polars para uma operação específica. Sua mensagem de commit é o único registro do seu raciocínio. Sem isso, você fica na dúvida ou precisa vasculhar as conversas do Slack e os tickets do JIRA.

Aqui estão mais algumas razões concretas pelas quais a mensagem de commit do git é importante.

As revisões de código ficam mais rápidas com mensagens de commit claras. O revisor pode dar uma olhada na mensagem, entender a intenção e focar em verificar se a implementação está de acordo. Mensagens vagas fazem com que os revisores tenham que tentar entender o que você quis dizer a partir do diferenças.

A depuração também fica mais fácil. Quando aparecer um bug, você vai usar git log ou git blame pra rastrear quando o código problemático foi introduzido. Uma mensagem como “corrigir bug de autenticação” não diz nada. Uma mensagem como “corrigir verificação de expiração do token no middleware de autenticação” te leva direto ao problema.

A colaboração em equipe depende de um histórico legível. Quando alguém entra no seu projeto ou continua de onde você parou, vai ler os commits pra entender como a base de código evoluiu. Mensagens claras transformam seu histórico Git em uma documentação que realmente ajuda.

O ponto principal é que uma mensagem descritiva de commit leva de 15 a 30 segundos para ser escrita. Mas isso evita muitas confusões no futuro.

Princípios básicos de uma boa mensagem de commit no Git

Boas mensagens de commit seguem alguns princípios simples — nada mais do que isso.

Escreva para os leitores do futuro

Sua mensagem de commit não é pra você agora — é pra quem ler daqui a seis meses.

Essa pessoa pode ser um novo membro da equipe tentando entender por que o código funciona de uma determinada maneira. Pode ser você, tentando lembrar por que tomou uma decisão específica. De qualquer jeito, eles não vão ter o contexto que você tem hoje.

Concentre-se na intenção eno raciocínio, não apenas no que mudou. O diff mostra o que mudou. Sua mensagem deve explicar por que mudou e qual problema ela resolve.

Seja claro e direto

Mensagens curtas e descritivas são mais fáceis de ler quando você está olhando dezenas de commits.

Uma mensagem como “adicionar cache” é meio vaga. Uma mensagem como “adicionar cache Redis para respostas da API” te diz exatamente o que rolou. Você pode ler em git log --oneline e saber logo de cara o que o commit faz.

O assunto do e-mail deve responder: o que esse commit faz? Se você precisa de mais de 50-60 caracteres pra responder isso, provavelmente tá fazendo muitas alterações de uma vez.

Seja consistente

A consistência em todo o seu repositório torna o histórico previsível e mais fácil de analisar.

Quando cada commit segue o mesmo formato, dá pra dar uma olhada rápida no histórico. Você sabe onde procurar o tipo de alteração, o escopo e a descrição. Equipes que usam formatos consistentes também podem automatizar tarefas como gerar registros de alterações ou filtrar commits por tipo.

Escolha um estilo e mantenha-o. Se sua equipe usa imperativos no presente, não mude aleatoriamente para o pretérito.

Explique o que e por que (não como)

O código mostra como você resolveu o problema. Sua mensagem de commit deve explicar qual era o problema e por que você escolheu essa solução.

Não escreva “refatorou load_data() para usar compreensão de lista em vez de loop for”. Escreva “acelerar o carregamento de dados em 40% para arquivos CSV grandes”. A primeira mensagem fala sobre a mudança no código. O segundo explica o impacto.

Adicione contexto quando isso ajudar os futuros leitores a entender sua decisão. Se você tentou três abordagens diferentes antes de decidir por essa, fale sobre isso. Se tiver algum relatório de bug ou decisão de design relacionado, dá uma olhada nele.

A estrutura de uma mensagem de commit do Git

A maioria das mensagens de commit do Git segue uma estrutura padrão de três partes: linha de assunto, corpo e rodapé.

Assunto

A linha de assunto é um resumo de uma linha que aparece nas listas de pull requests e de git log --oneline.

Tente não passar de 50 caracteres, se possível, e 72 no máximo. Esse limite garante que a mensagem seja exibida corretamente na saída do terminal e na interface do usuário do GitHub sem ser cortada. Se você não consegue encaixar seu resumo em 50 caracteres, provavelmente está tentando descrever muitas alterações em um único commit.

Use o modo imperativo - escreva “adicionar recurso” em vez de “recurso adicionado” ou “adiciona recurso”. Pense nisso como completar a frase “Se aplicado, este commit irá...”. Então, “Se aplicado, este commit adicionará o cache Redis” soa natural, enquanto “Se aplicado, este commit adiciona o cache Redis” não soa.

Exemplos:

• fix null pointer exception in data loader

• add caching layer for API responses

• remove deprecated pandas functions

Corpo (quando necessário)

Pule o corpo para alterações simples. Se o assunto do e-mail já explica tudo sobre o commit, tá tudo certo.

Adicione um corpo quando precisar explicar por que fez a alteração ou fornecer contexto que ajude os futuros leitores. Deixe uma linha em branco entre o assunto e o corpo - o Git usa isso pra separar as duas partes.

O corpo deve responder a perguntas como: Que problema isso resolve? Por que você escolheu essa abordagem? Tem algum efeito colateral ou limitação? Você pensou em outras soluções?

Quebre as linhas em 72 caracteres para manter o texto legível na saída do terminal. A maioria dos editores de texto consegue fazer isso automaticamente.

Exemplo:

add Redis caching for API responses

API response times were hitting 2-3 seconds for repeated queries.
Added Redis with 5-minute TTL to cache query results. This drops
response time to ~50ms for cached queries.

Considered using in-memory cache but Redis lets us scale horizontally
if needed.

Rodapé (opcional)

Use o rodapé para referenciar questões relacionadas, solicitações de pull ou alterações significativas.

Se o seu commit resolver um problema do GitHub, coloque Fixes #123 ou Closes #456 no rodapé. O GitHub vai fechar automaticamente a questão quando o commit for mesclado. Para alterações significativas, adicione BREAKING CHANGE: seguido de uma descrição do que mudou e como fazer a migração.

Exemplo:

remove support for Python 3.7

Python 3.7 reached end-of-life in June 2023. This commit drops
support and updates minimum version to Python 3.8.

BREAKING CHANGE: Python 3.7 users must upgrade to 3.8 or later.
Closes #789

Você não precisa de um rodapé para a maioria dos commits — só quando estiver vinculando referências externas ou marcando alterações significativas.

Tipos comuns de mensagens de commit do Git e quando usá-las

Muitos projetos usam prefixos de tipo de commit para categorizar as alterações rapidamente.

Você não precisa decorar uma lista rígida de rótulos. O objetivo é ajudar os leitores a perceber rapidamente que tipo de mudança rolou sem precisar ler todo o diff.

Aqui estão quatro categorias que você precisa saber:

• As alterações nas funcionalidades introduzem novas funcionalidades. Use prefixos como feat: ou add: quando estiver criando algo novo — um novo endpoint de API, uma função de processamento de dados ou um recurso voltado para o usuário. Exemplo: feat: add CSV export for analysis results.

• Correções de bugs resolvem os problemas que já existem. Use “ fix: ” quando estiver corrigindo um comportamento que não funcionou como esperado. Isso pode ser qualquer coisa, desde uma exceção de ponteiro nulo até cálculos errados no seu modelo. Exemplo: fix: handle missing values in preprocessing pipeline.

• Atualizações da documentação melhoram os comentários do código, os arquivos README ou a documentação embutida. Use “ docs: ” quando você não estiver mudando como o código funciona, só explicando melhor. Exemplo: docs: add usage examples for data loader class.

• Reestruturação e manutenção melhora a estrutura do código sem mudar o comportamento. Use refactor: quando estiver reorganizando o código para torná-lo mais limpo ou mais fácil de manter. Use o ` chore: ` para tarefas rotineiras, como atualizar dependências ou alterar configurações de compilação. Exemplos: refactor: extract validation logic into separate module ou chore: update pandas to 3.0.0.

Escolha o tipo que melhor descreve sua mudança e siga em frente — a consistência é mais importante do que escolher o rótulo “perfeito”.

Regras para escrever uma mensagem de commit Git melhor

Aqui tá uma lista de regras que vão deixar suas mensagens de commit mais úteis.

• Mantenha a linha de assunto com menos de 50 caracteres. Isso garante que ele seja exibido corretamente em git log --oneline, na lista de commits do GitHub e na saída do terminal sem truncamento. Se você não conseguir encaixar sua mensagem em 50 caracteres, tente usar no máximo 72.

• Use o modo imperativo. Escreva “adicionar recurso” em vez de “recurso adicionado” ou “adiciona recurso”. O assunto do e-mail deve completar a frase “Se aplicado, este commit irá...”. Então, “Se aplicado, este commit adicionará cache” está certo.

• Separe o assunto e o corpo do e-mail com uma linha em branco. O Git usa essa linha em branco pra diferenciar o resumo da explicação detalhada. Sem isso, as ferramentas Git podem mostrar sua mensagem de forma errada.

• Pule o ponto final no final da linha de assunto. Você tá economizando caracteres e o assunto não é uma frase completa mesmo. Escreva fix null pointer in loader em vez de fix null pointer in loader.

• Escreva a primeira palavra do assunto com letra maiúscula. Escreva Add caching for API calls em vez de add caching for API calls. Isso faz com que seu histórico de commits pareça consistente e profissional.

• Use o corpo para explicar o porquê, não o quê. O diff mostra o que mudou. Seu corpo deve explicar o motivo por trás da mudança, as alternativas que você considerou e quaisquer concessões que você fez.

• Queime o texto do corpo em 72 caracteres. Isso evita problemas de quebra de linha na saída do terminal e mantém suas mensagens de commit legíveis em diferentes ferramentas.

• Faça cada commit atômico. Uma alteração lógica por commit. Se você estiver corrigindo um bug e refatorando o código, divida-os em dois commits com mensagens separadas.

Exemplos de uma boa mensagem de commit no Git

Aqui estão alguns exemplos reais que mostram como são boas mensagens de commit para diferentes cenários.

Uma solução simples

fix: handle NaN values in feature engineering

The preprocessing pipeline crashed when encountering NaN values
in the 'age' column. Added fillna() with median imputation before
scaling features.

Isso funciona porque identifica o problema (falhas NaN), explica onde ocorreu (pipeline de pré-processamento, coluna de idade) e descreve a solução (imputação mediana).

Um novo recurso

feat: add model performance tracking to MLflow

Added automatic logging of model metrics, parameters, and artifacts
to MLflow after each training run. This replaces our manual CSV
logging and makes experiment comparison much easier.

Metrics tracked: accuracy, precision, recall, F1 score
Training time also logged for performance monitoring.

Bons commits de recursos explicam o que você criou, por que é útil e quaisquer detalhes que ajudem os leitores a entender o escopo.

Uma refatoração

refactor: split data_loader.py into separate modules

Moved dataset classes to datasets.py, transformation logic to
transforms.py, and utility functions to utils.py. The original
file was 800+ lines and hard to navigate.

No behavior changes - all tests still pass.

As mensagens de refatoração devem deixar claro que você não mudou a funcionalidade, só a estrutura. A frase “todos os testes ainda são aprovados” deixa os revisores tranquilos.

Uma atualização da documentação

docs: add examples for custom loss functions

Previous documentation showed only built-in loss functions.
Added three examples: weighted cross-entropy, focal loss, and
custom regression loss with L1 regularization.

Each example includes code and explanation of when to use it.

Os commits de documentação devem explicar o que você documentou e por que isso foi necessário.

Referenciando um problema ou ticket

fix: prevent memory leak in batch processing

Large datasets caused memory usage to grow unbounded during batch
processing. The issue was holding references to processed batches
in the results list.

Changed to yield results instead of accumulating them in memory.
Memory usage now stays constant regardless of dataset size.

Fixes #247

Quando você mencionar um problema, inclua contexto suficiente para que alguém possa entender a solução sem precisar clicar no ticket. A opção “ Fixes #247 ” (Fechar automaticamente esta questão quando esta confirmação for mesclada) na parte inferior diz ao GitHub para fechar automaticamente a questão quando esta confirmação for mesclada.

Todos os exemplos seguem o mesmo padrão: comece com o que mudou, explique o motivo, acrescente contexto que ajude os futuros leitores e mencione questões relacionadas quando for relevante.

Commits convencionais como padrão de mensagem de commit do Git

Os commits convencionais são um formato popular que adiciona estrutura às mensagens de commit por meio de um padrão de prefixo simples.

Formato básico

O formato é assim: type(scope): description.

O tipo descreve o tipo de alteração que você está fazendo - feat para recursos, fix para correções de bugs, docs para documentação, refactor para reestruturação de código e assim por diante. Oescopo é opcional e mostra qual parte do código mudou - tipo (auth) ou (api). A descrição explica o que você fez.

Exemplos:

feat(api): add endpoint for batch predictions
fix(auth): prevent token expiration edge case
docs(readme): add installation instructions for Windows
refactor(data): extract validation logic to separate module

Só não esqueça que isso é uma convenção, não uma regra. O Git não liga se você usa esse formato. Basicamente, é uma decisão da equipe sobre como organizar suas mensagens para manter a consistência e usar as ferramentas certas.

Quando os commits convencionais são úteis

As equipes que automatizam os processos de lançamento aproveitam ao máximo os commits convencionais.

As ferramentas podem analisar seu histórico de commits e gerar automaticamente registros de alterações. Quando você marca uma versão, a ferramenta verifica os commits desde a última versão, agrupa-os por tipo (feat, fix, docs) e cria um changelog formatado. Isso evita o trabalho manual de acompanhar o que mudou entre as versões.

Os commits convencionais também suportam a automação do versionamento semântico. Se todos os seus commits desde o último lançamento estiverem corretos, a ferramenta atualiza a versão do patch (1.2.3 → 1.2.4). Se você adicionou recursos, isso aumenta a versão secundária (1.2.3 → 1.3.0). Alterações significativas provocam um grande salto na versão (1.2.3 → 2.0.0).

Mas se sua equipe não usa lançamentos automáticos ou geração de changelog, os commits convencionais podem ser um exagero. A estrutura ajuda mais as máquinas do que as pessoas, então tenha isso em mente.

Erros comuns a evitar nas mensagens de commit do Git

Mesmo desenvolvedores experientes às vezes cometem erros ao escrever mensagens de commit, mas isso tem mais a ver com preguiça do que com falta de conhecimento.

Aqui estão alguns erros que você deve evitar.

Mensagens vagas ou genéricas

Mensagens como “corrigir bug” ou “atualizar código” não dizem nada para quem ler depois.

Quando você tá procurando uma mudança específica em git log, você vai dar uma olhada em várias confirmações. Uma mensagem que diz “corrigir bug” faz você abrir o diff e ler o código pra entender o que foi corrigido. Uma mensagem que diz “corrigir ponteiro nulo no pré-processamento de dados” mostra na hora se esse é o commit que você está procurando.

Mensagens genéricas só fazem todo mundo perder tempo. Se você não consegue lembrar o que mudou bem o suficiente para escrever uma mensagem específica, provavelmente não deve fazer o commit ainda.

Misturando mudanças não relacionadas

Cada commit deve ter uma mudança lógica.

Quando você corrige um bug e refatora código não relacionado no mesmo commit, você dificulta as revisões de código e torna o git bisect inútil. Se esse commit causar uma regressão, alguém vai ter que descobrir qual parte da mudança causou isso. Se eles quiserem reverter apenas a correção do bug, não podem — eles também reverterão a refatoração.

Você deve sempre dividir as alterações em commits separados. Conserte o bug em um commit e refatore em outro. Cada commit deve ser algo que você possa reverter de forma independente, sem danificar a base de código.

Se você já misturou as alterações localmente, use o comando ` git add -p ` para preparar partes dos arquivos separadamente e confirmá-las em blocos lógicos.

Deixando mensagens sobre trabalhos em andamento

Commits com mensagens como "WIP" ou "correção temporária" são aceitáveis localmente, mas não devem chegar ao branch principal ramo.

Antes de juntar seu ramo de recurso, dá uma geral no seu histórico de commits. Esquecer Transforma commits WIP em commits significativos com mensagens adequadas. Reescreva “asdf” e “tentando algo” em descrições que expliquem o que você realmente fez.

Use o git rebase -i para juntar commits, reescrever mensagens e reorganizar as alterações antes de enviar. Sua equipe deve ver um histórico claro do que mudou e por quê, sem precisar ler todo o seu processo de depuração.

Melhores práticas para equipes que usam mensagens de commit do Git

Se sua equipe quer tornar o histórico do Git realmente útil, você precisa de consistência. Aqui estão algumas práticas recomendadas a seguir.

Combinam logo um estilo comum. Decida se você vai usar commits convencionais, um formato personalizado ou só um conjunto de regras básicas. Escolha uma abordagem e mantenha-a em toda a equipe. Quando metade dos seus commits dizem “feat: adicionar recurso” e a outra metade dizem “Adicionado novo recurso”, seu histórico fica mais difícil de analisar e a automação pode falhar.

O estilo não importa tanto quanto todos seguirem ele. Algumas equipes preferem o imperativo no presente (“adicionar recurso”), outras usam o pretérito (“recurso adicionado”). Os dois funcionam bem se forem usados direitinho.

Documente suas convenções em algum lugar acessível. Adicione um arquivo CONTRIBUTING.md ao seu repositório explicando o formato da sua mensagem de commit com exemplos. Inclua isso nos documentos de integração para os novos membros da equipe. Quando alguém perguntar “como devo formatar este commit?”, indique a documentação em vez de explicar novamente.

Sua documentação deve abordar o formato básico que você usa, quando adicionar um corpo em vez de manter apenas uma linha de assunto, como referenciar problemas ou tickets e alguns exemplos reais do seu repositório.

Use mensagens de commit durante as revisões de código. Boas mensagens de commit tornam as revisões de pull requests mais rápidas e focadas. Os revisores podem ler as mensagens de commit para entender a progressão das alterações antes de mergulhar no código.

Ao revisar, verifique as mensagens de commit da mesma forma que verifica o código. Se uma mensagem estiver confusa ou enganosa, peça para que seja reescrita antes de mesclá-la. Um PR com commits claros é mais fácil de revisar, mais fácil de reverter se necessário e mais fácil de entender posteriormente.

Conclusão

Uma mensagem de commit clara leva 30 segundos para ser escrita, mas evita horas de confusão depois.

Pense no seu histórico de commits como uma documentação que acompanha o seu código. Quando você escreve “corrigir bug” em vez de “corrigir ponteiro nulo no pré-processamento de dados”, você está fazendo todo mundo que ler esse commit depois perder tempo — incluindo você mesmo.

Trate suas mensagens de commit como código. Se você não colocaria um código mal feito e sem comentários em produção, também não coloque mensagens de commit mal feitas. Use o modo imperativo, mantenha as linhas de assunto com menos de 50 caracteres, explique o motivo no corpo do texto quando necessário e torne cada commit atômico.

Agora você já sabe como escrever mensagens de commit que façam sentido. Para levar suas habilidades para o próximo nível, inscreva-se no nosso curso Git Intermediário.