Hooks do pre-commit

O pre-commit executa verificações de linting, formatação e tipo automaticamente antes de cada commit do git. Problemas são pegos localmente em segundos em vez de minutos na CI depois.

Receita

uv add --group dev pre-commit
uv run pre-commit install

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.9.0
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format

uv run pre-commit run --all-files

Quando usar isso:

Desenvolvedores esquecem de executar o lint antes de fazer o push
A CI falha em detalhes de formatação que atrasam as revisões
Novos membros da equipe precisam de salvaguardas desde o primeiro dia

Exemplo de Trabalho

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.9.0
    hooks:
      - id: ruff
        args: [--fix, --exit-non-zero-on-fix]
      - id: ruff-format
 
  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.14.0
    hooks:
      - id: mypy
        additional_dependencies: [pydantic>=2]
        args: [src/]
 
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v5.0.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-added-large-files
        args: [--maxkb=500]

uv run pre-commit install
git commit -m "feat: add billing module"
# ruff + mypy rodam automaticamente; commit bloqueado em caso de falha

O que isso demonstra:

Hooks rodam apenas em arquivos preparados (rápido)
--fix autocorre antes de bloquear
O hook mypy verifica tipos com as dependências do projeto
Hooks genéricos pegam acidentes de espaço em branco e arquivos grandes

Mergulho Profundo

Como Funciona

pre-commit install escreve um script .git/hooks/pre-commit
No git commit, cada hook roda em um ambiente isolado
Hooks que falham bloqueiam o commit; arquivos corrigidos podem precisar ser re-preparados
pre-commit run --all-files simula uma execução completa (útil na CI)

Desempenho dos Hooks

Hook	Tempo Típico	Escopo
ruff	<1s	Arquivos preparados
ruff-format	<1s	Arquivos preparados
mypy	5-30s	Caminhos configurados
trailing-whitespace	<1s	Arquivos preparados

Armadilhas

Mypy lento em cada commit - frustrante para os desenvolvedores. Correção: execute mypy apenas na CI; mantenha o ruff no pre-commit.
Não atualizar rev do hook - conjuntos de regras desatualizados. Correção: pre-commit autoupdate trimestralmente.
Hooks não instalados após o clone - commits pulam as verificações. Correção: documente pre-commit install no README; adicione pre-commit run --all-files na CI.
Hooks de correção alteram arquivos, mas o commit prossegue - --exit-non-zero-on-fix re-prepara o problema. Correção: use o argumento; re-adicione os arquivos corrigidos.
Versões de hook diferentes localmente vs CI - resultados inconsistentes. Correção: fixe rev na configuração; a CI executa a mesma configuração.

Alternativas

Alternativa	Use Quando	Não Use Quando
Apenas CI	Equipe muito pequena	Desenvolvedores enviam código quebrado com frequência
lefthook	Precisa de hooks paralelos mais rápidos	Ecossistema é menor
husky	Monorepo com JS + Python	Repositório apenas Python

FAQs

Como pular hooks uma vez?

git commit --no-verify (use com moderação, nunca como política padrão da equipe).

Como executar hooks manualmente?

pre-commit run --all-files ou pre-commit run ruff --all-files.

O mypy deve estar no pre-commit?

Para projetos pequenos, sim. Para bases de código grandes, mypy apenas na CI é mais rápido para o fluxo de desenvolvimento.

Como adicionar um hook?

Adicione uma entrada de repositório em .pre-commit-config.yaml e execute pre-commit install.

Hooks funcionam no Windows?

Sim. O pre-commit suporta Windows com Python instalado.

Como compartilhar a configuração?

Faça o commit de .pre-commit-config.yaml. Cada desenvolvedor executa pre-commit install.

Hooks podem rodar na CI?

Sim: pre-commit run --all-files como um passo da CI. Pega desenvolvedores que pulam a instalação.

Como excluir um arquivo?

exclude: ^migrations/ na configuração do hook ou filtro types.

E se um hook precisar de dependências do projeto?

Use additional_dependencies na configuração do hook (como com mypy + pydantic).

Com que frequência atualizar?

Trimestralmente ou ao atualizar as versões do ruff/mypy em pyproject.toml.

Relacionados

Configuração do Ruff - configuração do hook ruff
mypy & pyright na CI - verificação de tipos
Linting na CI/CD - pipeline de CI
Integração com Editor - loop de feedback do IDE

Versões da Pilha: Esta página foi escrita para Python 3.14.0, FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, e uv 0.6+.

Hooks do pre-commit

O pre-commit executa verificações de linting, formatação e tipo automaticamente antes de cada commit do git. Problemas são pegos localmente em segundos em vez de minutos na CI depois.

Receita

uv add --group dev pre-commit
uv run pre-commit install

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.9.0
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format

uv run pre-commit run --all-files

Quando usar isso:

Desenvolvedores esquecem de executar o lint antes de fazer o push
A CI falha em detalhes de formatação que atrasam as revisões
Novos membros da equipe precisam de salvaguardas desde o primeiro dia

Exemplo de Trabalho

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.9.0
    hooks:
      - id: ruff
        args: [--fix, --exit-non-zero-on-fix]
      - id: ruff-format
 
  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.14.0
    hooks:
      - id: mypy
        additional_dependencies: [pydantic>=2]
        args: [src/]
 
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v5.0.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-added-large-files
        args: [--maxkb=500]

uv run pre-commit install
git commit -m "feat: add billing module"
# ruff + mypy rodam automaticamente; commit bloqueado em caso de falha

O que isso demonstra:

Hooks rodam apenas em arquivos preparados (rápido)
--fix autocorre antes de bloquear
O hook mypy verifica tipos com as dependências do projeto
Hooks genéricos pegam acidentes de espaço em branco e arquivos grandes

Mergulho Profundo

Como Funciona

pre-commit install escreve um script .git/hooks/pre-commit
No git commit, cada hook roda em um ambiente isolado
Hooks que falham bloqueiam o commit; arquivos corrigidos podem precisar ser re-preparados
pre-commit run --all-files simula uma execução completa (útil na CI)

Desempenho dos Hooks

Hook	Tempo Típico	Escopo
ruff	<1s	Arquivos preparados
ruff-format	<1s	Arquivos preparados
mypy	5-30s	Caminhos configurados
trailing-whitespace	<1s	Arquivos preparados

Armadilhas

Mypy lento em cada commit - frustrante para os desenvolvedores. Correção: execute mypy apenas na CI; mantenha o ruff no pre-commit.
Não atualizar rev do hook - conjuntos de regras desatualizados. Correção: pre-commit autoupdate trimestralmente.
Hooks não instalados após o clone - commits pulam as verificações. Correção: documente pre-commit install no README; adicione pre-commit run --all-files na CI.
Hooks de correção alteram arquivos, mas o commit prossegue - --exit-non-zero-on-fix re-prepara o problema. Correção: use o argumento; re-adicione os arquivos corrigidos.
Versões de hook diferentes localmente vs CI - resultados inconsistentes. Correção: fixe rev na configuração; a CI executa a mesma configuração.

Alternativas

Alternativa	Use Quando	Não Use Quando
Apenas CI	Equipe muito pequena	Desenvolvedores enviam código quebrado com frequência
lefthook	Precisa de hooks paralelos mais rápidos	Ecossistema é menor
husky	Monorepo com JS + Python	Repositório apenas Python

FAQs

Como pular hooks uma vez?

git commit --no-verify (use com moderação, nunca como política padrão da equipe).

Como executar hooks manualmente?

pre-commit run --all-files ou pre-commit run ruff --all-files.

O mypy deve estar no pre-commit?

Para projetos pequenos, sim. Para bases de código grandes, mypy apenas na CI é mais rápido para o fluxo de desenvolvimento.

Como adicionar um hook?

Adicione uma entrada de repositório em .pre-commit-config.yaml e execute pre-commit install.

Hooks funcionam no Windows?

Sim. O pre-commit suporta Windows com Python instalado.

Como compartilhar a configuração?

Faça o commit de .pre-commit-config.yaml. Cada desenvolvedor executa pre-commit install.

Hooks podem rodar na CI?

Sim: pre-commit run --all-files como um passo da CI. Pega desenvolvedores que pulam a instalação.

Como excluir um arquivo?

exclude: ^migrations/ na configuração do hook ou filtro types.

E se um hook precisar de dependências do projeto?

Use additional_dependencies na configuração do hook (como com mypy + pydantic).

Com que frequência atualizar?

Trimestralmente ou ao atualizar as versões do ruff/mypy em pyproject.toml.

Relacionados

Configuração do Ruff - configuração do hook ruff
mypy & pyright na CI - verificação de tipos
Linting na CI/CD - pipeline de CI
Integração com Editor - loop de feedback do IDE

Versões da Pilha: Esta página foi escrita para Python 3.14.0, FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, e uv 0.6+.

Hooks do pre-commit

Buscar na documentação

Hooks do pre-commit