Guia completo sobre Git Hooks: Instalação, uso e dicas

Os hooks do Git permitem automatizar tarefas no seu fluxo de trabalho, executando scripts antes ou depois de ações do Git, como commits ou pushes. Elas ajudam a detectar problemas logo no início, fazer com que as normas sejam seguidas e até resolver problemas automaticamente.

Digamos que você escreveu um script para fazer valer os padrões de estilo do código. Você pode adicionar esse script a um gancho que é executado antes de um commit. Agora, sempre que alguém tentar fazer um commit, o hook vai rodar. Se o código passar nas verificações do gancho, o commit vai ser aprovado. Se não for o caso, o commit é bloqueado.

E não se trata apenas de sinalizar problemas. Você também pode personalizar o script para resolver esses problemas antes que o commit aconteça. Neste artigo, vou falar sobre tudo o que você precisa saber sobre os hooks do Git, o que são, quais são importantes e como implementá-los de forma eficaz.

O que são Git Hooks?

Os hooks do Git executam automaticamente scripts personalizados quando determinadas ações do Git ocorrem, como antes ou depois de um commit, push ou merge. Eles já vêm com o Git, então não precisa instalar nenhuma biblioteca externa.

Quando você inicializa um repositório Git, o Git cria os hooks por padrão. Você vai achá-los dentro do diretório .git/hooks. Elas vêm com extensões d .sample, que impedem que elas sejam executadas por padrão. Se você quiser que eles sejam executados por padrão, basta remover a extensão .sample.

Você pode escrever os ganchos em qualquer linguagem de script executável. Por exemplo, dentro do arquivo de gancho pré-confirmação, você pode adicionar um script que verifica se há comentários “A fazer” nos arquivos em fase de preparação e bloqueia a confirmação se encontrar algum. Isso quer dizer que toda vez que você tentar fazer um commit, o Git vai procurar comentários que começam com “To-do” e vai falhar se as tarefas pendentes existirem. Assim, você pode criar ganchos personalizados para diferentes ações do git, como pós-confirmação, pré-fusão, pré-envio e muito mais.

Tipos de ganchos Git

Antes de mergulharmos nos exemplos práticos, vamos entender os dois tipos de hooks do Git. 

Hooks do lado do cliente: categorias e exemplos comuns

Os ganchos do lado do cliente são executados em máquinas locais durante operações do Git, como commit, rebase e push. Aqui estão alguns ganchos de cliente populares e seus casos de uso específicos.

• pré-confirmação: É executado antes mesmo de você digitar a mensagem de commit. Você pode usar isso pra reforçar estilos de código, rodar testes ou checar erros de sintaxe antes de fazer o commit. 
• prepare-commit-msg: É executado depois que o Git cria a mensagem de commit padrão, mas antes que o editor de mensagens de commit apareça. Esse gancho pode mudar ou substituir a mensagem padrão com base na lógica do script personalizado. 
• commit-msg: Esse gancho rola logo depois que a mensagem de commit é salva, mas antes que o Git termine o commit. É a sua última chance de garantir que as regras das mensagens de commit, como formatação, estrutura ou marcação, sejam seguidas.
• pós-confirmação: É executado depois que um commit é criado. É frequentemente usado para notificações (como enviar uma mensagem no Slack após um commit) ou registro (armazenamento de metadados de commit).
• post-checkout: Executa após um comando git checkout bem-sucedido. Ele é iniciado quando você altera ramificações ou verifica um commit ou caminho específico. Você pode usá-lo para reconstruir dependências do projeto, excluir arquivos temporários ou notificar sobre um novo branch.
• pós-fusão: Executa após uma operação de mesclagem bem-sucedida. É normalmente usado pra atualizar dependências, imprimir mensagens de mesclagem ou limpar caches.
• pré-rebase: Executa antes de uma operação de rebase. Você pode usar isso pra evitar rebase em branches protegidos, fazer testes antes de permitir o rebase ou parar um rebase se tiver alterações não confirmadas.
• pré-push: Executa antes de enviar as alterações. Isso ajuda a evitar envios para branches protegidos ou a executar testes pré-envio.
• pós-reescrita: É executado depois que o Git reescreve os commits com sucesso. Isso é acionado em operações como git commit --amend (que reescreve o último commit) ou git rebase (que reescreve uma série de commits). Use isso pra atualizar referências ou acionar testes e etapas de CI depois de reescrever.
• pre-applypatch: Chamado pelo comando ` git am `, esse gancho rola depois que um patch é aplicado na árvore de trabalho, mas antes de um novo commit ser criado. Se as verificações neste gancho falharem, ele pode sair com um status diferente de zero e impedir que o patch seja confirmado.
• post-applypatch: O Git faz isso depois de aplicar o patch e criar o commit. Não dá pra cancelar o commit, mas funciona bem pra registrar ou mandar notificações.
• applypatch-msg: O Git faz isso antes de git am aplicar o patch. Use isso pra conferir ou editar a mensagem de commit sugerida pro patch.

Hooks do lado do servidor: categorias e casos de uso

Os ganchos do lado do servidor funcionam em servidores Git remotos e são acionados quando acontecem eventos remotos, como antes ou depois de enviar para um repositório.

• pré-recebimento: O controle remoto faz isso antes de aceitar um comando. Você pode usá-lo para garantir um estilo de código consistente entre os usuários ou executar verificações de segurança antes de aceitar alterações de um cliente.
• atualização: Enquanto o pré-recebimento rola uma vez por push, o gancho de atualização rola para cada referência (ramo ou tag) que está sendo alterada em um único push.
• pós-recebimento: É executado depois que a operação git push é concluída. É frequentemente usado para enviar notificações, fazer registros detalhados ou acionar pipelines de CI/CD.
• pós-atualização: Executa depois que o Git atualiza todas as referências em um push. Você pode usá-lo para notificações simples porque, ao contrário do post-receive, ele não consegue acessar os registros antigos e novos de cada atualização de referência.
• transação de referência: Ele é acionado quando uma transação de referência é preparada, confirmada ou abortada, de modo que pode ser executado várias vezes. Use isso pra validar ou rejeitar atualizações em várias referências numa única transação, ou pra registrar e auditar alterações de referência.
• clique para finalizar a compra: É acionado quando você faz um git push para um branch que está atualmente verificado no remoto. Com esse gancho, você pode atualizar arquivos no servidor depois de um envio, registrar as alterações ou bloquear envios não seguros diretamente para o diretório de trabalho.
• pre-auto-gc: É executado logo antes do Git acionar a coleta automática de lixo. Você pode usá-lo para registrar o início da coleta de lixo, bloqueá-la durante operações que consomem muitos recursos ou lidar com quaisquer tarefas necessárias antes da coleta de lixo.
• proc-receive: É executado quando o comando git-receive-pack processa um envio recebido. Ele atualiza as referências (ramificações e tags) no repositório remoto e mostra os resultados pro cliente.

Configurando Git Hooks

Nesta seção, você vai encontrar as etapas para instalar e configurar os ganchos git. Você também vai ver como criar ganchos personalizados do zero. 

Mecânica de instalação e configuração

Quando você inicializa um repositório Git, o Git cria automaticamente um conjunto de hooks dentro da pasta .git/hooks. Para vê-los, abra seu terminal e vá até a raiz do repositório onde você executou o comando ` git init`. A partir daí, abra o diretório oculto .git e, em seguida, o subdiretório hooks. Um simples comando ` cd ` faz tudo isso pra você e dá acesso ao subdiretório hooks.

cd .git/hooks

Quando você entrar, vai ver os ganchos padrão com a extensão .sample. Para ativar um gancho padrão, tire a extensão .sample desse gancho e torne-o executável.

Por exemplo, use o comando abaixo para tirar a extensão .sample do gancho pré-confirmação.

mv .git/hooks/pre-commit.sample .git/hooks/pre-commit

Depois, torne-o executável usando o comando abaixo:

chmod +x .git/hooks/pre-commit

Isso inclui editar e ativar os ganchos padrão. Para criar ganchos personalizados do zero, siga estas etapas.

Para abrir um novo arquivo no .git/hooks/, execute:

nano .git/hooks/commit-msg

Crie o script neste arquivo. Exemplo:

 #!/bin/sh
echo "✅ Commit message hook triggered"

Salve e saia, depois torne-o executável:

chmod +x .git/hooks/commit-msg 

No exemplo acima, sempre que o commit é aprovado, os hooks mostram uma mensagem. " Commit message hook triggered"

Tem outra maneira de configurar ganchos personalizados. Quando você inicializa um repositório, o Git inclui hooks padrão. Você pode editar esses padrões usando diretórios de modelos. 

Funciona assim: Quando você executa o comando ` git init`, o Git copia o conteúdo do diretório de modelos global para o diretório ` .git/ ` do novo repositório, incluindo os ganchos. Se você adicionar scripts de hook personalizados ao diretório de modelos global, cada novo repositório que você criar vai herdar esses hooks personalizados automaticamente.

Criando e personalizando scripts de gancho

Primeiro, você precisa descobrir o que quer alcançar. É pegar mensagens de commit vagas, evitar envios acidentais ou limpar caches? É importante definir o objetivo logo de cara, porque diferentes ganchos git têm diferentes finalidades, e você precisa saber qual usar. 

Por exemplo, se você quiser conferir o estilo da mensagem de commit, vai usar o gancho commit-msg. Se você quiser evitar certos envios para o branch principal, use um gancho pré-envio. 

Depois de escolher o gancho, a próxima decisão é a linguagem. No macOS e no Linux, um pequeno script Bash (ou simplesmente sh) costuma ser suficiente. No Windows, algumas equipes usam o PowerShell. 

Se o seu repositório é poliglota, talvez você prefira um interpretador universal como Python ou Node.js, pra que todo mundo possa rodar a mesma lógica. Então, o segredo é colocar um shebang (#!/bin/sh, #!/usr/bin/env python3, etc.) no começo, pra que o Git saiba como rodar o programa.

Um exemplo simples de gancho pré-confirmação que evita a confirmação de arquivos .env. Isso evita o envio acidental de chaves API confidenciais.

#!/bin/sh

# Block committing secrets
if git diff --cached --name-only | grep -q ".env"; then
  echo "❌ .env file detected in commit! Remove it before committing."
  exit 1
fi

exit 0

Quando você quiser desativar os hooks, a maneira mais fácil é renomeá-los temporariamente (mude pre-commit para pre-commit.off) ou remover sua permissão de execução. 

Mas, se você só precisa ignorar uma vez, use git commit --no-verify para pular os ganchos de commit e git push --no-verify para pular os ganchos de push. Você pode até desativar os hooks globalmente, apontando o Git para uma pasta vazia com git config core.hooksPath /dev/null.

Casos de uso comuns e exemplos de Git Hooks

Os hooks do Git são super úteis pra automatizar testes, verificações de segurança e garantir padrões de qualidade no seu fluxo de trabalho. 

Cenários práticos de automação

Aplique o estilo de código ou linting: O gancho pré-confirmação é frequentemente usado para automatizar a formatação do código e detectar possíveis erros antes que a confirmação seja realizada.

Por exemplo, no seguinte gancho pré-confirmação, o prettier cuida da formatação automaticamente e prepara as alterações antes de confirmar. Um linter pode então ser executado logo em seguida, e o commit só será bem-sucedido se o linting for aprovado. Se não der certo, o commit é interrompido.

#!/bin/sh

# Collect staged JS/TS files
FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(js|ts|tsx)$')
[ -z "$FILES" ] && exit 0

echo "Formatting with Prettier..."
npx --yes prettier --write $FILES

# Re-stage files that Prettier changed
echo "$FILES" | xargs git add

echo "Linting with ESLint..."
npx --yes eslint $FILES
STATUS=$?

if [ $STATUS -ne 0 ]; then
  echo "ESLint found issues. Fix them or commit with --no-verify if needed."
  exit $STATUS
fi

echo "Pre-commit checks passed."
exit 0

Executar testes automatizados: Você pode configurar os ganchos para rodar testes automáticos antes de enviar qualquer alteração. Por exemplo, o seguinte gancho pré-push descobre e executa automaticamente os pytests disponíveis no seu repositório antes de enviar as alterações.

#!/bin/sh
echo "Running tests before push..."
pytest -q
STATUS=$?
[ $STATUS -eq 0 ] || { echo "Tests failed. Push aborted."; exit $STATUS;

Bloqueie automaticamente o envio de dados confidenciais: Arquivos sensíveis como .env, .pem ou .key geralmente têm segredos. O exemplo de gancho pré-confirmação a seguir verifica esses padrões e bloqueia a confirmação se eles estiverem presentes.

#!/bin/sh
set -e

STAGED=$(git diff --cached --name-only --diff-filter=ACM)

# Block dotenv and private keys
echo "$STAGED" | grep -E '\.env(\.|$)|(^|/)\.env$|\.pem$|\.key$|id_rsa$' >/dev/null 2>&1 && {
  echo "Sensitive file detected in staged changes. Remove it from the commit."
  exit 1
}

Dicas para escrever hooks Git eficazes

Aqui, coloquei algumas dicas que achei úteis pra escrever hooks do Git. 

Mantenha os ganchos bem presos

Os ganchos são executados sempre que você aciona determinadas ações do Git, portanto, mantenha-os leves. Se você tiver conjuntos de testes grandes, execute-os em CI em vez de em hooks locais para obter um melhor desempenho. Executar linters, formatadores ou verificações em todo o repositório a cada commit vai te atrasar, então limite as verificações aos arquivos que realmente mudaram.

Manter a compatibilidade entre plataformas 

Garanta que seus ganchos funcionem bem em diferentes sistemas operacionais. Use shebangs portáteis, lide com os finais de linha de forma consistente (use LF em vez de CRLF) e não codifique caminhos absolutos. 

Em vez disso, use PATH e scripts de projeto locais como npm run lint ou python -m para que ele funcione em vários ambientes.

Estratégias de depuração

Adicione um registro detalhado ou um sinalizador de depuração (por exemplo, HOOK_DEBUG=1) para rastrear como o script é executado. Imprima detalhes como o diretório atual, o branch ou os arquivos que estão sendo preparados. Isso facilita acompanhar o fluxo de execução e identificar onde as coisas dão errado.

Teste os ganchos com diferentes entradas e simule cenários de falha localmente antes de enviar as alterações. Se um gancho bloquear o progresso de repente, você pode ignorá-lo temporariamente com a flag ` --no-verify ` do Git ou usando variáveis de ambiente feitas pra pular ganchos.

Para manter um comportamento consistente entre os sistemas operacionais, evite comandos específicos do sistema operacional e prefira linguagens de script portáteis.

Documente os ganchos de forma clara

Uma boa documentação melhora o entendimento da equipe e facilita a integração de novos membros. Mantenha um README central detalhando a finalidade, o comportamento e o uso de cada gancho. Inclua como executar, pré-requisitos, solução de problemas e dicas de contorno. Além disso, forneça instruções de instalação/configuração. 

Técnicas avançadas de implementação e melhores práticas para Git Hooks

Se você é um usuário mais avançado, essas dicas podem ajudar:

Otimização do desempenho

Para otimizar o desempenho em fluxos de trabalho complexos, reduza as dependências externas evitando bibliotecas pesadas. Isso reduz o tempo de inicialização e diminui os pontos de falha. 

Armazene em cache os resultados de processos caros, como linting, para poder reutilizá-los quando os arquivos não tiverem sido alterados. 

Se os ganchos tiverem várias verificações, coloque-os em paralelo para que funcionem ao mesmo tempo. Além disso, modularize os scripts de gancho. Isso quer dizer que os ganchos de estrutura são como pequenos componentes reutilizáveis que só fazem o que é necessário de acordo com o contexto.

Encadeamento de ganchos e orquestração

Use o encadeamento de ganchos para executar vários ganchos em um único evento git. Por exemplo, em um gancho pré-confirmação, você pode querer executar a verificação de código, depois os testes e, por fim, formatar o código, tudo em sequência. Cada comando é executado um após o outro e, se algum falhar (sair com status diferente de zero), os comandos seguintes podem ser ignorados para evitar um commit incorreto. 

Quando as ações do gancho são independentes, você também pode executá-las em paralelo para economizar tempo. É aí que você usa a orquestração para gerenciar a execução das tarefas na ordem certa.

Gerenciamento de configuração 

Cada repositório tem seu próprio diretório .git/hooks. Isso quer dizer que, se você quiser as mesmas verificações (por exemplo, linting) em vários projetos, vai ter que copiar e colar em todos eles. Uma maneira melhor é gerenciar os hooks de forma centralizada, para que todos os repositórios possam acessá-los e executá-los.

Você pode fazer isso com um único comando: git config --global core.hooksPath ~/.githooks. Isso diz ao Git para procurar hooks na pasta ~/.githooks. Todos os ganchos que você criar lá serão automaticamente compartilhados em todos os seus repositórios.

Você também pode deixar a lógica do hook mais dinâmica com arquivos de configuração (JSON ou YAML). Em vez de codificar lógicas diferentes para cada repositório, seu script de hook pode ler o arquivo de configuração desse repositório e aplicar as regras corretas automaticamente.

Execução condicional

Dentro dos scripts de gancho, você pode adicionar condições simples para que eles só sejam executados quando for relevante. Isso pode significar verificar o nome do branch atual, ver quais arquivos realmente mudaram ou ler uma variável de ambiente que diz para eles pularem.

Se você quiser mais controle, use uma estrutura como o pre-commit, onde você declara em um arquivo de configuração quais ganchos são executados em qual estágio. Você também pode adicionar lógica condicional, como executar hooks apenas em determinados branches, pular hooks com variáveis ou até mesmo adicionar condições baseadas em tempo. Isso deixa seus scripts de gancho dinâmicos e adaptados aos fluxos de trabalho reais.

Estratégias de colaboração e compartilhamento 

Tem duas maneiras de centralizar os ganchos do git e compartilhar entre repositórios e equipes:

Modelos Git

Quando você inicializa um repositório, o Git adiciona alguns ganchos padrão no diretório ` git/hooks `. Esses vêm do modelo padrão do Git.

Para criar hooks personalizados de forma centralizada, você pode criar um diretório de modelos Git, escrever seus hooks lá e configurar o Git globalmente para usar esse novo diretório como modelo padrão. 

git config --global init.templateDir /path/to/hooks-template

Mas esse método não tem controle de versão para os ganchos. Isso é super útil se seus ganchos mudam raramente. Se você atualiza os hooks com frequência e precisa controlar as versões, é melhor usar o próximo método.

Repositório git central

Crie um repositório central dedicado e controlado por versão e guarde todos os seus scripts de hook personalizados nesse repositório, separado dos repositórios do projeto. Assim, você pode fazer atualizações nos hooks independentemente da base de código do projeto. 

Esses ganchos devem ser padronizados, ou seja, evite codificar caminhos ou valores vinculados a um único repositório.

Essa configuração é super útil para equipes, já que todo mundo pode pegar atualizações regularmente e sincronizá-las nos seus projetos. 

Uma maneira mais eficiente é usar um script de configuração que clona o repositório central de hooks e copia os scripts de hook para o diretório .git/hooks de cada projeto. Exemplo de script de configuração: 

#!/usr/bin/env bash
set -euo pipefail

# Location of the shared hooks template repo
HOOKS_TEMPLATE_REPO="git@github.com:your-org/git-hooks-template.git"
HOOKS_TEMPLATE_DIR="$HOME/.git-hooks-template"

# Clone or update the template repo
 echo "Cloning hooks template repo..."
 git clone "$HOOKS_TEMPLATE_REPO" "$HOOKS_TEMPLATE_DIR"

# The repo where you want hooks installed
TARGET_REPO="${1:-$(pwd)}"
TARGET_HOOKS_DIR="$TARGET_REPO/.git/hooks"

# --- Copy strategy ---
echo "Copying hooks into $TARGET_HOOKS_DIR..."
cp -r "$HOOKS_TEMPLATE_DIR/"* "$TARGET_HOOKS_DIR/"

# 4. Make sure hooks are executable
chmod +x "$TARGET_HOOKS_DIR"/* || true

echo "✅ Hooks installed successfully into $TARGET_REPO"

Outra opção é usar links simbólicos. Você pode vincular o diretório .git/hooks de cada projeto aos scripts no seu repositório de hooks controlado por versão. Então, sempre que você atualizar o repositório central, os hooks vão se atualizar automaticamente porque o link simbólico aponta para ele.

Para manter a confiabilidade desse sistema, crie um processo claro para a manutenção dos ganchos. Os membros da equipe devem propor alterações nos hooks com pull requests, fazer a fusão só depois de revisar e manter a documentação atualizada conforme os hooks evoluem. 

Integrando Git Hooks com fluxos de trabalho de desenvolvimento

Os hooks do Git são super importantes na integração contínua (CI). Para contextualizar, CI significa juntar as mudanças com frequência e, em seguida, executar compilações e testes para detectar problemas antecipadamente. Ao conectar ganchos com ferramentas de CI/CD como Jenkins, GitHub Actions ou GitLab CI, você pode acionar compilações, executar testes e até mesmo implantar aplicativos automaticamente com base em eventos Git.

Por exemplo, um gancho pré-recebimento do lado do servidor executa um script personalizado no servidor Git antes de aceitar um push. Se o script não funcionar, o servidor vai rejeitar o envio. Você pode usar isso pra conferir se a última compilação de CI nessa ramificação foi aprovada antes de permitir o envio. Essa execução de CI pode incluir verificações de cobertura de código, testes unitários ou de integração, ou até mesmo varreduras de segurança.

Os ganchos também podem automatizar tarefas de implantação. Um gancho pós-recebimento pode acionar um webhook que inicia um pipeline de CI/CD. Quando o código é mesclado no main, ele automaticamente inicia o ciclo de compilação → implantação → lançamento.

Considerações de segurança e melhores práticas 

Se você mantém ganchos centrais para facilitar a colaboração e compartilhar informações, certifique-se de que o diretório de ganchos tenha permissões de arquivo seguras para impedir o acesso não autorizado. Só usuários confiáveis devem ter acesso de gravação. 

Você sempre precisa validar as entradas ou parâmetros que seus scripts de hook recebem para evitar ataques de injeção de código. Por exemplo, valida as entradas em relação a padrões rígidos, como permitir apenas nomes de ramificações com caracteres alfanuméricos e traços, ou tags que correspondam a vMAJOR.MINOR.PATCH. 

Nunca coloque dados confidenciais em scripts de hook. Em vez disso, use variáveis de ambiente ou ferramentas específicas de gerenciamento de segredos para fornecer credenciais com segurança durante a execução. Você pode integrar ferramentas como o Gitleaks com ganchos pré-confirmação para fazer varreduras de segurança em informações confidenciais nas alterações que você está prestes a confirmar.

Alguém pode redirecionar seu gancho para enviar o código ou as informações para um servidor diferente. Então, limita quais domínios seus hooks podem alcançar. Use um proxy ou firewall para bloquear servidores de destino desconhecidos. Além disso, certifique-se de que seus registros não mostrem informações confidenciais nas mensagens exibidas. 

Conclusão

Os hooks do Git são uma maneira poderosa de automatizar tarefas e aplicar padrões diretamente no seu fluxo de trabalho de desenvolvimento. Eles ajudam em tudo, desde o estilo do código e testes até a implantação e verificações de segurança.

Ao usá-los bem, você reduz erros, economiza tempo e torna a colaboração entre as equipes mais tranquila.

Comece com verificações simples antes do commit e, em seguida, experimente configurações mais avançadas, como orquestração, gerenciamento central ou integrações de CI/CD. Se você usa o Git e quer melhorar suas habilidades, dá uma olhada nesse curso avançado de Git.