Automação de Git Hooks

Automatize a aplicação de qualidade de código no nível do Git. Configure hooks que fazem lint, formatam, testam e validam antes que commits e pushes cheguem ao seu pipeline de CI — detectando problemas em segundos, em vez de minutos.

Quando Usar Essa Habilidade

• O usuário pede para "configurar git hooks" ou "adicionar pre-commit hooks"
• Configurando Husky, lint-staged ou o framework pre-commit
• Aplicando convenções de mensagens de commit (Conventional Commits, commitlint)
• Automatizando linting, formatação ou verificação de tipos antes de commits
• Configurando pre-push hooks para executores de testes
• Migrando do Husky v4 para o v9+ ou adotando hooks do zero
• O usuário menciona "pre-commit", "commit-msg", "pre-push", "lint-staged" ou "githooks"

Fundamentos de Git Hooks

Git hooks são scripts que rodam automaticamente em pontos específicos do fluxo de trabalho do Git. Eles ficam em .git/hooks/ e não são controlados por versão por padrão — é por isso que ferramentas como o Husky existem.

Tipos de Hooks e Quando Eles Disparam

Git Hooks Nativos (Sem Framework)

# Create a pre-commit hook manually
cat > .git/hooks/pre-commit << 'EOF'
#!/bin/sh
set -e

# Run linter on staged files only
STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(js|ts|jsx|tsx)$' || true)

if [ -n "$STAGED_FILES" ]; then
  echo "🔍 Linting staged files..."
  echo "$STAGED_FILES" | xargs npx eslint --fix
  echo "$STAGED_FILES" | xargs git add  # Re-stage after fixes
fi
EOF
chmod +x .git/hooks/pre-commit

Problema: .git/hooks/ é apenas local e não é compartilhado com a equipe. Use um framework em vez disso.

Husky + lint-staged (Projetos Node.js)

O padrão moderno para projetos JavaScript/TypeScript. O Husky gerencia os Git hooks; o lint-staged roda comandos apenas em arquivos staged para velocidade.

Configuração Rápida (Husky v9+)

# Install
npm install --save-dev husky lint-staged

# Initialize Husky (creates .husky/ directory)
npx husky init

# The init command creates a pre-commit hook — edit it:
echo "npx lint-staged" > .husky/pre-commit

Configurar lint-staged em package.json

{
  "lint-staged": {
    "*.{js,jsx,ts,tsx}": [
      "eslint --fix --max-warnings=0",
      "prettier --write"
    ],
    "*.{css,scss}": [
      "prettier --write",
      "stylelint --fix"
    ],
    "*.{json,md,yml,yaml}": [
      "prettier --write"
    ]
  }
}

Adicionar Linting de Mensagem de Commit

# Install commitlint
npm install --save-dev @commitlint/cli @commitlint/config-conventional

# Create commitlint config
cat > commitlint.config.js << 'EOF'
module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [2, 'always', [
      'feat', 'fix', 'docs', 'style', 'refactor',
      'perf', 'test', 'build', 'ci', 'chore', 'revert'
    ]],
    'subject-max-length': [2, 'always', 72],
    'body-max-line-length': [2, 'always', 100]
  }
};
EOF

# Add commit-msg hook
echo "npx --no -- commitlint --edit \$1" > .husky/commit-msg

Adicionar Pre-Push Hook

# Run tests before pushing
echo "npm test" > .husky/pre-push

Estrutura Completa de Diretórios do Husky

project/
├── .husky/
│   ├── pre-commit        # npx lint-staged
│   ├── commit-msg        # npx --no -- commitlint --edit $1
│   └── pre-push          # npm test
├── commitlint.config.js
├── package.json          # lint-staged config here
└── ...

Framework pre-commit (Python / Poliglota)

Framework agnóstico de linguagem que funciona com qualquer projeto. Hooks são definidos em YAML e rodam em ambientes isolados.

Configuração

# Instalar (Python necessário)
pip install pre-commit

# Criar configuração
cat > .pre-commit-config.yaml << 'EOF'
repos:
  # Verificações integradas
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.6.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml

…