O Que É fetch-depth?

fetch-depth é uma configuração de checkout de CI que controla quantos commits de histórico um job baixa, equilibrando velocidade contra acesso ao passado.

fetch-depth é o botão que você ajusta para decidir quanto histórico do Git um job de CI puxa. Defina um valor baixo e os checkouts ficam rápidos, mas o histórico fica raso; defina para buscar tudo e você obtém o log completo ao custo de um clone mais lento. Escolher o valor certo é uma otimização de CI pequena, mas real.

O que fetch-depth controla

fetch-depth mapeia diretamente para a profundidade do clone. Uma profundidade de 1 busca apenas o commit que está sendo construído. Um número maior busca essa quantidade de commits de histórico. Por convenção, uma profundidade de 0 significa buscar o histórico completo sem nenhum truncamento.

Definindo fetch-depth

Em um checkout do GitHub Actions, fetch-depth é um parâmetro na etapa de checkout.

steps:
  - uses: actions/checkout@v4
    with:
      fetch-depth: 0

Quando você precisa de mais profundidade

Alguns jobs exigem histórico além do commit mais recente: calcular um diff contra a branch base, derivar uma versão a partir de tags ou gerar um changelog percorrem os commits para trás. Se uma ferramenta reportar histórico ausente ou uma revisão desconhecida, aumentar fetch-depth costuma ser a solução.

fetch-depth e desempenho de CI/CD

Como o checkout roda em cada job, fetch-depth tem um efeito desproporcional no tempo total do pipeline para repositórios grandes. A profundidade rasa padrão mantém tudo rápido; aumente apenas para os jobs específicos que precisam de histórico. Em runners gerenciados, deixar a maioria dos jobs rasos mantém a frota eficiente.

Escolhendo um valor

• Use profundidade 1 (o padrão) para jobs simples de build e teste.
• Use profundidade 0 para etapas de changelog, diff ou versão a partir de tag.
• Aumente a profundidade apenas nos jobs que realmente precisam de histórico.
• Lembre-se de que buscas mais profundas deixam cada execução que as usa mais lenta.

Principais conclusões

• fetch-depth define quantos commits de histórico um job de CI baixa.
• Profundidade 0 significa histórico completo; profundidade 1 busca apenas o commit do build.
• Mantenha raso para velocidade; aprofunde apenas para diffs, tags ou changelogs.

Guias relacionados