Automatizando Verificações de Código com Git Pre-Commit Hooks

Todo desenvolvedor conhece a frustração de fazer push de código apenas para ver os pipelines de CI/CD falharem devido a problemas de formatação ou erros de linting. E se você pudesse detectar esses problemas antes mesmo deles chegarem ao seu repositório? Os git pre-commit hooks oferecem uma solução poderosa que executa verificações automatizadas localmente, economizando tempo e mantendo a qualidade consistente do código em toda a sua equipe.

Este artigo te guia através da configuração de git pre-commit hooks usando o framework pre-commit, configurando ferramentas essenciais como ESLint, Prettier e Black, e implementando melhores práticas que mantêm seu fluxo de desenvolvimento suave e eficiente.

O Que São Git Pre-Commit Hooks?

Git hooks são scripts que o Git executa antes ou depois de eventos como commit, push e receive. Um git pre-commit hook especificamente executa depois que você adiciona mudanças ao stage, mas antes do Git criar o commit. Se o hook sai com um status diferente de zero, o Git aborta o commit, dando a você a chance de corrigir os problemas primeiro.

Embora você possa escrever hooks como scripts shell simples em .git/hooks/, gerenciá-los torna-se complexo conforme seu projeto cresce. É aí que o framework pre-commit brilha—ele fornece uma forma padronizada de gerenciar e compartilhar hooks em sua equipe.

Por Que Usar o Framework Pre-Commit?

O framework pre-commit resolve vários pontos problemáticos dos Git hooks nativos:

• Instalação e atualizações fáceis: Hooks são versionados e instalados via uma configuração YAML simples
• Agnóstico a linguagens: Execute linters Python, formatadores JavaScript e scripts shell a partir de uma configuração
• Execução seletiva: Hooks executam apenas em arquivos modificados, mantendo os commits rápidos
• Consistência da equipe: Compartilhe o mesmo arquivo .pre-commit-config.yaml em toda a sua equipe

Configurando Pre-Commit em Seu Projeto

Primeiro, instale o pacote pre-commit:

pip install pre-commit

Crie um arquivo .pre-commit-config.yaml na raiz do seu projeto. Aqui está uma configuração prática que cobre necessidades comuns:

repos:
  # Basic file fixes
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.5.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-added-large-files

  # Python formatting with Black
  - repo: https://github.com/psf/black
    rev: 24.2.0
    hooks:
      - id: black
        files: \.py$

  # Python type checking with Mypy
  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.8.0
    hooks:
      - id: mypy
        additional_dependencies: [types-all]
        files: \.py$

  # JavaScript/TypeScript with Prettier
  - repo: https://github.com/pre-commit/mirrors-prettier
    rev: v3.1.0
    hooks:
      - id: prettier
        files: \.(js|jsx|ts|tsx|json|css|md)$

  # JavaScript/TypeScript linting with ESLint
  - repo: https://github.com/pre-commit/mirrors-eslint
    rev: v8.56.0
    hooks:
      - id: eslint
        files: \.(js|jsx|ts|tsx)$
        additional_dependencies:
          - eslint-config-standard
          - eslint-plugin-react

  # Run project tests
  - repo: local
    hooks:
      - id: pytest
        name: pytest
        entry: pytest
        language: system
        pass_filenames: false
        always_run: true

Instale os git hooks:

pre-commit install

Agora seus hooks executarão automaticamente a cada commit. Para executá-los manualmente em todos os arquivos:

pre-commit run --all-files

Otimizando Performance dos Hooks

Velocidade importa—hooks lentos desencorajam desenvolvedores de fazer commit frequentemente. Siga essas práticas:

Execute hooks apenas em arquivos staged: O framework pre-commit faz isso por padrão, mas certifique-se de que seus hooks customizados respeitam esse padrão.

Use ferramentas rápidas: Escolha Ruff ao invés de Flake8 para Python, ou Biome ao invés de ESLint para JavaScript quando velocidade é crítica.

Pule verificações caras localmente: Reserve suítes de teste abrangentes para CI/CD. Hooks locais devem focar em ganhos rápidos como formatação e linting básico.

Paralelizar quando possível: Algumas ferramentas suportam execução paralela. Por exemplo, pytest pode executar testes em paralelo com pytest-xdist.

Melhores Práticas para Adoção da Equipe

Fazer sua equipe adotar pre-commit hooks requer implementação cuidadosa:

Comece pequeno: Inicie com hooks não intrusivos como remoção de espaços em branco no final das linhas. Adicione verificações mais rigorosas gradualmente.

Documente a configuração: Inclua instruções de instalação no seu README. Torne isso parte do seu processo de onboarding.

Lide com diferenças de ambiente: Use hooks agnósticos a linguagens quando possível. Para ferramentas específicas de linguagem, certifique-se de que seu .pre-commit-config.yaml especifica versões compatíveis.

Forneça válvulas de escape: Às vezes desenvolvedores precisam contornar hooks. A flag --no-verify pula todos os hooks:

git commit --no-verify -m "Emergency fix"

Use isso com parcimônia e documente quando é apropriado.

Abordagens Alternativas

Embora pre-commit seja o framework mais popular, existem alternativas:

Husky: Popular em projetos JavaScript, integra bem com scripts npm.

Git hooks nativos: Scripts shell diretos em .git/hooks/ oferecem controle máximo mas carecem de portabilidade.

Lefthook: Alternativa rápida e multiplataforma com suporte a execução paralela.

Para a maioria das equipes, pre-commit oferece o melhor equilíbrio entre recursos, performance e suporte do ecossistema.

Armadilhas Comuns e Soluções

Falhas de hook no CI: Certifique-se de que ambientes CI têm todas as dependências necessárias instaladas. Considere executar pre-commit run --all-files como um passo do CI.

Problemas específicos de plataforma: Teste hooks em todas as plataformas que sua equipe usa. Use Docker para ambientes consistentes se necessário.

Conflitos de merge em arquivos de configuração: Mantenha mudanças no .pre-commit-config.yaml mínimas e atômicas. Atualize versões de hooks em commits separados.

Conclusão

Git pre-commit hooks transformam qualidade de código de um processo reativo para um proativo. Ao detectar problemas antes deles entrarem no seu repositório, você economiza tempo, reduz mudanças de contexto e mantém padrões mais altos em toda sua base de código. Comece com hooks básicos de formatação, adicione gradualmente linters e verificadores de tipo, e sempre priorize velocidade para manter o fluxo de trabalho da sua equipe suave.

A chave para adoção bem-sucedida está em equilibrar minuciosidade com experiência do desenvolvedor. Hooks rápidos e focados que fornecem valor imediato tornar-se-ão uma parte indispensável do fluxo de trabalho da sua equipe.

FAQs

Gain control over your UX

See how users are using your site as if you were sitting next to them, learn and iterate faster with OpenReplay. — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.