Clones Rasos no Git: Quando e Como Usá-los

Clones rasos no Git buscam apenas parte do histórico de commits. Eles são úteis quando um job de CI, etapa de implantação ou tarefa de inspeção rápida precisa do código atual, mas não de anos de histórico.

Eles não são o melhor padrão para toda estação de trabalho de desenvolvedor. Um clone raso pode economizar tempo e espaço em disco, mas também limita comandos baseados em histórico até que você busque mais commits.

O que é um Clone Raso?

Um clone padrão busca histórico suficiente para trabalho normal em branches, inspeção de histórico, checkout de tags antigas e investigação offline. Um clone raso trunca esse histórico em uma profundidade que você escolhe.

Por exemplo, --depth 1 busca o commit do topo para o branch selecionado. --depth 50 busca histórico mais recente, mas ainda não a ancestralidade completa.

Benefícios de Usar Clones Rasos

O principal benefício é o menor custo de transferência:

Checkout inicial mais rápido para repositórios grandes.
Menos uso de disco em agentes de build de curta duração.
Menor uso de largura de banda em redes lentas ou medidas.
Menos histórico para o Git processar durante o clone inicial.

Em um pipeline de CI que constrói o commit atual e descarta o espaço de trabalho, um clone raso é frequentemente uma vitória limpa.

Desvantagens e Limitações dos Clones Rasos

A troca é o histórico ausente:

git log para no limite raso.
git blame pode não conseguir seguir alterações mais antigas.
Tags ou commits antigos podem estar indisponíveis até serem buscados.
Rebases e merges podem ser mais difíceis se o Git precisar de uma base de merge ausente.
Alguns fluxos de trabalho de lançamento ou auditoria esperam um histórico completo.

Se seu trabalho frequentemente envolve depuração de regressões antigas, preparação de lançamentos ou backport de alterações, comece com um clone completo.

Como Criar um Clone Raso

Use git clone --depth:

git clone --depth <número> <url_do_repositório>

Por exemplo, para clonar um repositório e buscar apenas os últimos 10 commits:

git clone --depth 10 https://github.com/exemplo/repositorio-grande.git

Para um job de build que precisa apenas do topo do branch:

git clone --depth 1 https://github.com/exemplo/projeto.git

Para clonar um branch específico:

git clone --depth 1 -b develop https://github.com/exemplo/projeto.git

Você também pode adicionar --single-branch quando quiser apenas histórico para aquele branch:

git clone --depth 1 --single-branch --branch develop https://github.com/exemplo/projeto.git

Gerenciando Clones Rasos

Buscando Mais Histórico (Aprofundando o Clone)

Se você precisar de mais histórico após clonar, aprofunde o repositório:

git fetch --deepen=50 origin

Isso busca 50 commits adicionais além do limite raso atual.

Você também pode definir a profundidade total desejada:

git fetch --depth=100 origin

O ponto importante: git remote set-depth não é um comando Git válido. A profundidade é controlada através das opções clone e fetch.

Buscando Tags

Clones rasos podem não incluir todas as tags, especialmente tags apontando para commits mais antigos. Busque tags apenas se seu fluxo de trabalho precisar delas:

git fetch --tags origin

Desfazendo o Raso de um Repositório

Para converter um clone raso em um clone completo, busque o resto do histórico:

git fetch --unshallow origin

Este comando baixará o histórico restante do repositório remoto.

Enviando de um Clone Raso

Enviar de um clone raso pode funcionar quando seus novos commits são baseados no topo do branch remoto que você buscou. Ainda é uma escolha ruim para desenvolvimento de longo prazo porque o histórico ausente pode tornar rebases, resolução de conflitos e revisão mais difíceis.

Se você encontrar problemas de push ou merge relacionados ao histórico, busque mais histórico ou desfaça o raso do clone antes de continuar.

Quando Usar Clones Rasos

Use-os quando o job for de curta duração e o histórico não for importante:

Checkout de CI/CD.
Inspeção somente leitura.
Ambientes de reprodução temporários.
Builds de documentação.
Repositórios grandes em redes lentas.

Quando Não Usar Clones Rasos

Evite-os quando você precisar regularmente de:

git log, git blame ou git bisect profundos.
Trabalho de lançamento que usa tags antigas.
Trabalho complexo de merge ou rebase.
Depuração offline através do histórico.
Fluxos de trabalho de contribuição que esperam um clone completo.

Conclusão Prática

Use git clone --depth 1 para jobs descartáveis que precisam apenas do código mais recente. Use um clone completo para desenvolvimento normal, a menos que você tenha uma razão clara para não fazê-lo.

Se um clone raso começar a atrapalhar, aprofunde-o com git fetch --deepen=<número> origin ou converta-o com git fetch --unshallow origin. Isso geralmente é mais rápido e seguro do que lutar contra erros de histórico ausente um comando de cada vez.