Pre-commit Hooks

Um pre-commit hook executa archgate check --staged antes de cada commit, de modo que as violações de arquitetura são pegas na máquina do desenvolvedor — antes que cheguem a um pull request. Como --staged verifica apenas os arquivos na área de staging do git, o hook se mantém rápido o suficiente para o uso diário.

Este guia mostra a abordagem com hook nativo do git, além dos dois gerenciadores de hooks comuns. Para a referência completa de flags, veja o guia de pre-commit da CLI em cli.archgate.dev.

Por que --staged

archgate check --staged restringe a avaliação aos arquivos em staging no git:

• Um projeto com centenas de arquivos-fonte, mas três arquivos em staging, verifica apenas esses três.
• Regras cujos globs files não casam com nada na área de staging são totalmente ignoradas.
• Verificações típicas de pre-commit terminam em menos de um segundo.

Quando uma regra falha, o comando sai com código 1 e o commit é bloqueado. As violações são impressas no stderr com o ID do ADR, o nome da regra, o caminho do arquivo e o número da linha, para que você possa localizá-las e corrigi-las imediatamente. Refaça o stage com git add e commite novamente.

Nota

Use --staged para hooks e o archgate check sem escopo (ou --base) para o CI. O escopo staged mantém o hook local rápido; o CI verifica o diff completo.

Hook nativo do git

Nenhuma ferramenta extra é necessária — o git procura por um executável em .git/hooks/pre-commit:

macOS / Linux

Crie o hook e torne-o executável:

cat > .git/hooks/pre-commit <<'EOF'
#!/bin/sh
archgate check --staged
EOF
chmod +x .git/hooks/pre-commit

Windows (PowerShell)

O Git para Windows executa hooks através do shell que vem junto, então um script POSIX sh funciona. Crie o arquivo com um shebang e sem a extensão .ps1:

@'
#!/bin/sh
archgate check --staged
'@ | Set-Content -NoNewline .git/hooks/pre-commit

Cuidado

.git/hooks/ não é versionado, então um hook nativo existe apenas na máquina que o criou. Para compartilhar um hook entre a equipe, use um gerenciador de hooks (abaixo) e versione sua configuração, ou aponte core.hooksPath para um diretório rastreado.

Gerenciadores de hooks

Gerenciadores de hooks armazenam a configuração do hook em um arquivo versionado, de modo que cada clone do repositório recebe os mesmos hooks. Ambos os gerenciadores abaixo executam archgate check --staged exatamente como o hook nativo faz.

Lefthook

O Lefthook é um gerenciador de git hooks rápido e multiplataforma. Adicione a verificação ao lefthook.yml:

lefthook.yml

pre-commit:
  commands:
    adr-check:
      run: archgate check --staged

Então instale os hooks:

lefthook install

Husky

O Husky é uma ferramenta popular de git hooks para projetos Node.js. Adicione a verificação ao hook de pre-commit:

.husky/pre-commit

archgate check --staged

Garanta que o hook seja executável:

chmod +x .husky/pre-commit

Rodando ao lado de outros hooks

Pre-commit hooks normalmente executam várias verificações. Cada comando roda de forma independente, e o commit é bloqueado se qualquer um sair com código diferente de zero. Com o Lefthook:

lefthook.yml

pre-commit:
  commands:
    lint:
      run: npm run lint
    typecheck:
      run: npm run typecheck
    adr-check:
      run: archgate check --staged

Flags úteis

O comando check aceita as mesmas flags aqui que em qualquer outro lugar; estas são as relevantes para hooks. A lista completa está na referência da CLI.

Flag	Propósito
--staged	Verifica apenas arquivos em staging no git — obrigatória para pre-commit
--verbose	Mostra regras que passaram e timing — útil ao depurar por que um hook está lento
--adr <id>	Verifica regras de um único ADR — útil para isolar uma regra durante a depuração
--json	Emite JSON — para encaminhar a scripts de relatório personalizados

Combine suas defesas

Pre-commit hooks são o ponto de aplicação mais cedo que um humano controla, mas podem ser contornados com --no-verify. Mantenha o gate de CI como a última linha de defesa autoritativa, e deixe os plugins de editor aplicarem os ADRs durante a codificação assistida por IA.

Relacionados

Integração com CI O gate de merge autoritativo com o archgate/check-action.

Guia de migração Adote o Archgate em um repositório existente.

Referência de pre-commit da CLI Documentação completa de flags e comportamento.