Padronizando Commits Git com um Script Bash: Uma Solução Simples para um Problema Comum

Padronizando Commits Git com um Script Bash: Uma Solução Simples para um Problema Comum Índice O que são Commits Semânticos e por que são importantes A origem do problema A solução: um hook Git em Bash Anatomia do script O hook de validação O gerenciador de hooks Instalação e uso Conclusão e lições aprendidas FAQ - Perguntas Frequentes Próximos passos Referências Bibliográficas O que são Commits Semânticos e por que são importantes Commits semânticos são uma convenção para escrever mensagens de commit padronizadas que comunicam claramente a intenção por trás de cada mudança no código. Esta abordagem surgiu da Convenção de Commits Convencionais (Conventional Commits), que por sua vez foi inspirada no Angular Commit Guidelines, utilizado pelo time do Google no desenvolvimento do Angular. A ideia central é que cada commit deve descrever explicitamente seu propósito através de um formato estruturado: tipo(escopo): descrição Origem e Evolução A convenção de commits semânticos ganhou popularidade por volta de 2015-2016, quando equipes de desenvolvimento começaram a perceber a necessidade de padronizar as mensagens de commit para facilitar a automação de processos como geração de changelogs e versionamento semântico. Inicialmente adotada por projetos JavaScript, a prática se espalhou para diversas linguagens e ecossistemas. Tipos de Commits Cada mensagem de commit começa com um "tipo" que indica a natureza da mudança: feat: introduz uma nova funcionalidade no código fix: corrige um bug ou problema docs: alterações apenas na documentação style: mudanças que não afetam o significado do código (espaços, formatação, etc.) refactor: alteração de código que não corrige um bug nem adiciona uma feature perf: melhoria de performance test: adição ou correção de testes build: alterações no sistema de build ou em dependências externas ci: mudanças nos arquivos de configuração de CI/CD chore: outras alterações que não modificam src ou arquivos de teste revert: reverte um commit anterior Onde: escopo: opcional, indica a parte do código afetada descrição: explica o que foi feito Esta convenção traz diversos benefícios: Legibilidade: Qualquer pessoa consegue entender rapidamente o propósito de um commit Automatização: Permite gerar changelogs e versionamento semântico automaticamente Organização: Facilita filtrar commits por tipo (apenas correções, apenas novas features) Histórico significativo: Transforma o histórico de commits em uma documentação valiosa Em equipes grandes ou projetos de longo prazo, essa padronização se torna ainda mais crucial, pois ajuda a manter todos alinhados sobre as mudanças realizadas. A origem do problema Ao trabalhar em projetos com múltiplos desenvolvedores, percebi a importância de manter um histórico de commits organizado e informativo. Minha motivação principal para criar este script veio de minha experiência anterior como desenvolvedor full stack, quando tive a oportunidade de implementar o Husky no ecossistema Node.js - uma ferramenta que simplesmente "trava" commits que não seguem o padrão desejado. Após ver o impacto positivo dessa prática, eu queria algo igualmente eficaz e simples para meus projetos Java atuais, sem necessidade de configurações complexas ou dependências adicionais. Embora existam algumas ferramentas semelhantes, como o JHusky (uma versão Java inspirada no Husky original) e alguns plugins Maven para hooks Git, descobri que muitas dessas soluções exigiam dependências específicas ou se integravam profundamente apenas com um único ecossistema. Eu queria algo verdadeiramente leve e portátil, que funcionasse em qualquer ambiente de desenvolvimento, independentemente das tecnologias utilizadas no projeto. Foi aí que decidi criar minha própria ferramenta usando Bash, uma linguagem disponível em praticamente qualquer ambiente de desenvolvimento, permitindo que equipes com tecnologias mistas pudessem aproveitar os benefícios de padronização de commits sem precisar instalar ferramentas específicas de linguagem. A solução: um hook Git em Bash Decidi então criar uma solução simples: um script Bash que instala um Git hook para validar mensagens de commit, garantindo que elas sigam o padrão de commits semânticos. Por que Bash? Porque está disponível em praticamente qualquer sistema Unix-like, não requer dependências externas, e qualquer desenvolvedor consegue modificá-lo para suas necessidades específicas. Apresentação do Script O script que desenvolvi tem duas partes principais: o hook commit-msg que faz a validação propriamente dita, e um gerenciador para instalar/remover esse hook em repositórios Git. Aqui está o que ele faz: Cria um hook commit-msg que valida mensagens de commit usando expressões regulares Mostra feedbacks visuais coloridos quando o commit é rejeitado Fornece exemplos corretos para ajudar o desenvolvedor Permite instalar o

Apr 28, 2025 - 20:55

Padronizando Commits Git com um Script Bash: Uma Solução Simples para um Problema Comum

Índice

O que são Commits Semânticos e por que são importantes
A origem do problema
A solução: um hook Git em Bash
Anatomia do script
- O hook de validação
- O gerenciador de hooks
Instalação e uso
Conclusão e lições aprendidas
FAQ - Perguntas Frequentes
Próximos passos
Referências Bibliográficas

O que são Commits Semânticos e por que são importantes

Commits semânticos são uma convenção para escrever mensagens de commit padronizadas que comunicam claramente a intenção por trás de cada mudança no código. Esta abordagem surgiu da Convenção de Commits Convencionais (Conventional Commits), que por sua vez foi inspirada no Angular Commit Guidelines, utilizado pelo time do Google no desenvolvimento do Angular.

A ideia central é que cada commit deve descrever explicitamente seu propósito através de um formato estruturado:

tipo(escopo): descrição

Origem e Evolução

A convenção de commits semânticos ganhou popularidade por volta de 2015-2016, quando equipes de desenvolvimento começaram a perceber a necessidade de padronizar as mensagens de commit para facilitar a automação de processos como geração de changelogs e versionamento semântico. Inicialmente adotada por projetos JavaScript, a prática se espalhou para diversas linguagens e ecossistemas.

Tipos de Commits

Cada mensagem de commit começa com um "tipo" que indica a natureza da mudança:

feat: introduz uma nova funcionalidade no código
fix: corrige um bug ou problema
docs: alterações apenas na documentação
style: mudanças que não afetam o significado do código (espaços, formatação, etc.)
refactor: alteração de código que não corrige um bug nem adiciona uma feature
perf: melhoria de performance
test: adição ou correção de testes
build: alterações no sistema de build ou em dependências externas
ci: mudanças nos arquivos de configuração de CI/CD
chore: outras alterações que não modificam src ou arquivos de teste
revert: reverte um commit anterior

Onde:

escopo: opcional, indica a parte do código afetada
descrição: explica o que foi feito

Esta convenção traz diversos benefícios:

Legibilidade: Qualquer pessoa consegue entender rapidamente o propósito de um commit
Automatização: Permite gerar changelogs e versionamento semântico automaticamente
Organização: Facilita filtrar commits por tipo (apenas correções, apenas novas features)
Histórico significativo: Transforma o histórico de commits em uma documentação valiosa

Em equipes grandes ou projetos de longo prazo, essa padronização se torna ainda mais crucial, pois ajuda a manter todos alinhados sobre as mudanças realizadas.

A origem do problema

Ao trabalhar em projetos com múltiplos desenvolvedores, percebi a importância de manter um histórico de commits organizado e informativo.

Minha motivação principal para criar este script veio de minha experiência anterior como desenvolvedor full stack, quando tive a oportunidade de implementar o Husky no ecossistema Node.js - uma ferramenta que simplesmente "trava" commits que não seguem o padrão desejado. Após ver o impacto positivo dessa prática, eu queria algo igualmente eficaz e simples para meus projetos Java atuais, sem necessidade de configurações complexas ou dependências adicionais.

Embora existam algumas ferramentas semelhantes, como o JHusky (uma versão Java inspirada no Husky original) e alguns plugins Maven para hooks Git, descobri que muitas dessas soluções exigiam dependências específicas ou se integravam profundamente apenas com um único ecossistema. Eu queria algo verdadeiramente leve e portátil, que funcionasse em qualquer ambiente de desenvolvimento, independentemente das tecnologias utilizadas no projeto.

Foi aí que decidi criar minha própria ferramenta usando Bash, uma linguagem disponível em praticamente qualquer ambiente de desenvolvimento, permitindo que equipes com tecnologias mistas pudessem aproveitar os benefícios de padronização de commits sem precisar instalar ferramentas específicas de linguagem.

A solução: um hook Git em Bash

Decidi então criar uma solução simples: um script Bash que instala um Git hook para validar mensagens de commit, garantindo que elas sigam o padrão de commits semânticos.

Por que Bash? Porque está disponível em praticamente qualquer sistema Unix-like, não requer dependências externas, e qualquer desenvolvedor consegue modificá-lo para suas necessidades específicas.

Apresentação do Script

O script que desenvolvi tem duas partes principais: o hook commit-msg que faz a validação propriamente dita, e um gerenciador para instalar/remover esse hook em repositórios Git.

Aqui está o que ele faz:

Cria um hook commit-msg que valida mensagens de commit usando expressões regulares
Mostra feedbacks visuais coloridos quando o commit é rejeitado
Fornece exemplos corretos para ajudar o desenvolvedor
Permite instalar o hook em um repositório específico ou em todos os repositórios do sistema
Oferece uma interface amigável para gerenciar os hooks

Anatomia do script

O hook de validação

A parte principal do script é o hook em si, que valida a mensagem de commit usando uma expressão regular:

pattern="^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\([a-zA-Z0-9_-]+\))?: .{1,}"

if ! [[ $commit_msg =~ $pattern ]]; then
    # Exibe mensagem de erro formatada com instruções
    # ...
    exit 1
fi

Esta expressão regular garante que cada commit comece com um tipo válido (feat, fix, docs, etc.), opcionalmente seguido por um escopo entre parênteses, e depois por uma descrição.

Quando uma mensagem não segue esse padrão, o script exibe uma mensagem de erro colorida que explica o formato correto e mostra exemplos:

draw_box "ERRO: Mensagem de commit não segue o padrão semântico!" "$RED"
echo -e "\n$RED""Seu commit:$RESET $commit_msg"
echo -e "\n$YELLOW$BOLD""O formato correto é:$RESET (): "
# ... explicação dos tipos válidos ...
echo -e "\n$BOLD$GREEN""Exemplos:$RESET"
draw_box "feat(login): adiciona validação de e-mail" "$GREEN"

Exemplo: A mensagem será exibida na aba de console do Git.

Exemplos rápidos

❌ Commits não semânticos (incorretos)	✅ Commits semânticos (corretos)
"Corrigido o bug de login"	`fix(auth): corrige validação de senha na tela de login`
"Adicionado novo botão"	`feat(ui): adiciona botão de exportar na tela de relatórios`
"Atualizando documentação"	`docs(readme): atualiza instruções de instalação`
"Melhorias no código"	`refactor(core): simplifica lógica de processamento de pagamentos`

O gerenciador de hooks

O script principal oferece uma interface de menu para:

Instalar o hook em um repositório específico ou globalmente
Remover hooks de um repositório específico ou globalmente
Sair do script

O menu é simples e intuitivo:

echo -e "${CYAN}===== ${BOLD}Gerenciador de Git Hook ($HOOK_NAME)${RESET}${CYAN} =====${RESET}"
echo -e "${BLUE}1)${RESET} ${BOLD}Instalar hook${RESET}"
echo -e "${BLUE}2)${RESET} ${BOLD}Remover hook${RESET}"
echo -e "${BLUE}3)${RESET} ${BOLD}Sair${RESET}"

Ao selecionar as opções 1 ou 2, você é apresentado a submenus que permitem escolher entre operações em um repositório específico ou em todos os repositórios do sistema.

Instalação e uso

A instalação do script é simples:

# Clone o repositório
git clone https://github.com/diegoSbrandao/git-hook-manager.git
cd git-hook-manager

# Torne o script executável
chmod +x install-windows-hook.sh

# Execute o script
./install-windows-hook.sh

Após executar o script, você verá um menu interativo:

===== Gerenciador de Git Hook (commit-msg) =====
1) Instalar hook
2) Remover hook
3) Sair
Escolha uma opção:

Opções do menu:

1) Instalar Hook

1.1) Instalar hook a partir de um caminho: Para adicionar o hook em um repositório específico.
1.2) Instalar hook em todos os repositórios do sistema: Para uma instalação global.

2) Remover Hook

2.1) Remover hook de um repositório específico: Remove apenas hooks instalados por este script.
2.2) Remover hooks de todos os repositórios do sistema: Para remoção global.

O script foi desenvolvido para ser compatível com Linux, macOS, WSL e Git Bash no Windows, exigindo apenas requisitos básicos como bash, find e grep, que geralmente já estão disponíveis nestes sistemas.

Conclusão e lições aprendidas

O que aprendi com essa experiência é que às vezes soluções simples resolvem problemas complexos. O script não passa de 150 linhas de código Bash, mas teve um impacto significativo na qualidade do nosso trabalho.

Também aprendi que padronização traz consistência, e consistência facilita a colaboração. Quando todos seguem o mesmo padrão, a comunicação flui melhor.

Por fim, aprendi que ferramentas que ajudam os desenvolvedores a seguir boas práticas são tão importantes quanto as boas práticas em si. Não adianta estabelecer regras se não facilitamos o cumprimento delas.

FAQ - Perguntas Frequentes

Q: O script impede commits que não sejam semânticos?

A: Sim, o hook rejeita automaticamente commits inválidos e exibe uma mensagem de erro explicativa com exemplos corretos.

Q: É possível personalizar os tipos de commit aceitos?

A: Sim, você pode editar o script e modificar a expressão regular que define os tipos válidos.

Q: O script funciona em ambientes Windows?

A: Sim, ele é compatível com Git Bash e WSL (Windows Subsystem for Linux) no Windows.

Q: A instalação afeta todos os meus repositórios automaticamente?

A: Não, você precisa escolher se deseja instalar em um repositório específico ou em todos, dando controle total ao usuário.

Q: O hook afeta commits já realizados?

A: Não, o hook valida apenas novos commits, não alterando o histórico existente.

Próximos passos

É importante destacar que este script está atualmente em versão beta e ainda está em desenvolvimento. Como parte dos planos futuros, pretendo expandir sua funcionalidade integrando-o como um plugin para Maven ou IntelliJ IDEA, tornando-o ainda mais acessível para desenvolvedores Java.

Quando estas versões estiverem disponíveis, atualizarei esta documentação com as novas informações e instruções de uso. Se você tem interesse em contribuir com este projeto ou tem sugestões para estas futuras implementações, não hesite em entrar em contato ou abrir uma issue no repositório.

Referências Bibliográficas

CHACON, S.; STRAUB, B. Pro Git. 2. ed. Apress, 2014. Disponível em: https://git-scm.com/book/en/v2
CONVENTIONAL COMMITS. Conventional Commits 1.0.0. Disponível em: https://www.conventionalcommits.org/

Nota: O projeto está licenciado sob a MIT License e está disponível em: https://github.com/diegoSbrandao/git-hook-manager.git. Sinta-se à vontade para adaptar às necessidades do seu projeto ou equipe. E se tiver sugestões de melhorias, ficarei feliz em recebê-las!