Trabalhando em um repositório grande com sparse checkout e partial clone

O que é

Um único repositório com muitos projetos é lento de clonar e confuso para trabalhar. O Git oferece três formas independentes de reduzir esse custo:

• Sparse checkout (git sparse-checkout set <dir>...) restringe quais caminhos são materializados na árvore de trabalho e no índice. A documentação descreve o modo cone, hoje o padrão, em que a entrada é uma lista de diretórios e não padrões no estilo do gitignore; o modo de padrões sem cone (non-cone) é explicitamente desaconselhado. A opção --sparse-index reduz o índice para acompanhar essa seleção.
• Partial clone (git clone --filter=blob:none) pede ao servidor que omita objetos de acordo com um filtro; blob:none omite todo o conteúdo dos arquivos até que seja necessário, e blob:limit=<size> omite apenas os blobs com esse tamanho ou maior. As notas de design explicam que o remoto passa a ser um remoto promisor (promisor remote) e que os objetos ausentes são buscados sob demanda, o que exige conexão e, como os objetos são buscados um a um, "tends to be slow" (tende a ser lento).
• Shallow clone (--depth <n>) trunca o histórico. É um mecanismo diferente, com limites próprios, e não é necessário para que o partial clone funcione.

Por que importa

O tempo de clone, o uso de disco e o tamanho das varreduras do git status crescem com o repositório inteiro, e não com a parte em que uma pessoa ou um job de CI realmente mexe. Aplicar a redução adequada transforma um checkout de vários gigabytes em uma árvore de diretórios do tamanho da tarefa.

Como aplicar

• Para desenvolvedores: git clone --filter=blob:none --sparse <url> (a opção --sparse começa apenas com os arquivos do nível superior) e depois git sparse-checkout set services/api libs/common.
• Inclua diretórios inteiros no cone; os arquivos irmãos de cada diretório ancestral são incluídos automaticamente, e é isso que deixa disponíveis os arquivos de build na raiz.
• Para jobs de CI que precisam de apenas um commit: um partial clone sem blobs (blobless) dos caminhos necessários, ou um shallow clone quando o histórico é irrelevante.
• Quando um build não encontrar um arquivo, consulte git sparse-checkout list; adicione o diretório em vez de desativar o modo sparse.
• Comandos que percorrem o histórico (git log -p, git blame) disparam buscas sob demanda em um partial clone; execute-os onde a rede seja rápida ou faça um prefetch antes.

Armadilhas

Ferramentas que varrem a árvore de trabalho presumem que o repositório inteiro está presente e podem reportar incorretamente diretórios ausentes. Padrões sem cone (non-cone) quebram o --sparse-index e são lentos. Trabalhar offline em um partial clone falha no primeiro blob ausente. Um shallow clone não consegue responder a nenhuma pergunta sobre o histórico além do ponto de corte.