O Conventional Commits é uma convenção simples para mensagens de commit. Ele fornece um conjunto leve de regras para criar um histórico de commits explícito e fácil de ler, além de facilitar a automação de ferramentas (como geração automática de changelogs e controle de versionamento semântico).
Para conferir a especificação oficial completa, acesse: conventionalcommits.org
Estrutura Básica de um Commit
A mensagem de commit deve ser estruturada da seguinte forma:
<tipo>(<escopo opcional>): <descrição curta>
<corpo opcional>
<rodapé opcional>
Tipos Principais de Commit
| Tipo | Quando Usar |
feat | Adiciona uma nova funcionalidade ao projeto |
fix | Corrige um bug ou erro no sistema |
docs | Mudanças exclusivamente na documentação |
style | Mudanças de formatação (espaçamentos, ponto e vírgula, etc.) que não afetam a lógica |
refactor | Refatoração de código sem alterar o comportamento funcional |
perf | Mudança de código focada em melhoria de performance |
test | Adição ou ajuste de testes automatizados |
build | Modificações no sistema de build ou dependências externas |
ci | Alterações em arquivos/configurações de Integração Contínua (CI) |
chore | Tarefas de manutenção diversa (não afetam o código-fonte em src nem testes) |
revert | Reverte um commit feito anteriormente |
Exemplos Simples
git commit -m "feat: adiciona login via Google"
git commit -m "fix: corrige erro de null pointer no checkout"
git commit -m "docs: atualiza README com instruções de instalação"
git commit -m "refactor: simplifica lógica de validação de CPF"
git commit -m "test: adiciona testes para serviço de pagamento"
git commit -m "chore: atualiza dependências do projeto"
Adicionando Escopo
O escopo indica a parte específica do código que foi afetada e vem entre parênteses logo após o tipo:
git commit -m "feat(auth): adiciona suporte a login com Google"
git commit -m "fix(api): corrige timeout na rota de usuários"
git commit -m "style(header): ajusta espaçamento do menu"
Indicando Breaking Changes (Mudanças Incompatíveis)
Existem duas formas de indicar mudanças que quebram a compatibilidade da aplicação com versões anteriores:
Opção 1: Adicionando o caractere !
git commit -m "feat(api)!: remove endpoint /v1/users deprecated"
Opção 2: Utilizando o rodapé BREAKING CHANGE
git commit -m "feat(api): renomeia parâmetro de busca
BREAKING CHANGE: o parâmetro 'q' foi renomeado para 'query'"
Commit Completo (com Corpo e Rodapé)
Quando a mudança for mais complexa, utilize o corpo para contextualizar a alteração:
git commit -m "fix(payment): corrige cálculo de desconto em pedidos grandes
O desconto não estava sendo aplicado corretamente quando o valor do pedido ultrapassava R$ 1000. Fixes #123"
Referenciando Issues
git commit -m "feat(cart): adiciona botão de remover item Closes #45"
Relação com Versionamento Semântico
Seguir esse padrão se conecta diretamente ao Semantic Versioning (MAJOR.MINOR.PATCH):
- fix – Incrementa o PATCH (ex: 1.0.0 => 1.0.1)
- feat – Incrementa o MINOR (ex: 1.0.0 => 1.1.0)
- BREAKING CHANGE (ou !) – Incrementa o MAJOR (ex: 1.0.0 => 2.0.0)
Boas Práticas
- Modo Imperativo: Escreva a descrição curta no imperativo (ex: “adiciona” em vez de “adicionado” ou “adicionando”).
- Tamanho Ideal: Mantenha a primeira linha com no máximo 50 a 72 caracteres.
- Sem Ponto Final: Não finalize o título/descrição curta com ponto (
.). - Foco do Corpo: Use o corpo para explicar o o quê e o porquê da mudança, e não o como.
- Padronização do Time: Seja consistente com os tipos e escopos adotados no projeto (se necessário, liste-os na documentação da equipe).