CS Fundamentals Trainer · Guias

Submódulos, subtrees, worktrees, clones parciais e sparse, e LFS no Git

O que cada ferramenta do Git para compartilhar código e lidar com repositórios grandes realmente faz, com saídas reais de comandos: submódulos (gitlinks, .gitmodules, HEAD destacado, update, ordem do push, remoção, armadilhas), subtrees, worktrees, clones rasos e parciais, sparse checkout, Git LFS e um fluxograma de decisão que inclui a opção do gerenciador de pacotes.

12 min de leitura

Mais cedo ou mais tarde um repositório precisa de código que mora em outro: uma biblioteca compartilhada, uma dependência copiada para dentro, um design system usado por cinco aplicações. Ou aparece o problema oposto: um repositório cresce tanto que clonar leva minutos. O Git tem várias ferramentas para esses casos, e elas costumam ser confundidas: submódulos, subtrees, worktrees, clones rasos e parciais, sparse checkout e Git LFS. Este guia explica cada uma pelo que ela realmente faz por baixo, mostra os comandos com a saída de execuções reais (Git 2.43) e termina com uma tabela para escolher. Supõe que você conhece commits e branches; o modelo de objetos está no guia "Git internals and CI/CD pipelines".

1. O problema e as opções

NecessidadeFerramentaIdeia
Usar o código de outro projeto em uma versão exata, mantendo-o como repositório separadoSubmóduloo repositório externo registra o id de um commit do interno
Copiar o código de outro projeto para o seu, com o histórico, sem fluxo especial para os outrosSubtreeos arquivos viram arquivos comuns no seu repositório
Várias branches abertas ao mesmo tempoWorktreeum repositório, vários diretórios de trabalho
Clonar mais rápido, com menos históricoClone raso (shallow)só os últimos N commits
Clonar mais rápido, com menos conteúdo de arquivosClone parcialblobs buscados quando necessários
Trabalhar em uma fatia de uma árvore grandeSparse checkoutsó alguns diretórios no disco
Arquivos binários grandesGit LFSo repositório guarda ponteiros pequenos; o conteúdo fica em outro lugar
Bibliotecas compartilhadas com versõesUm gerenciador de pacotesnão é Git: publique em um registro (muitas vezes a melhor resposta)

Antes de recorrer ao Git, pergunte se um pacote (npm, módulos Go, PyPI) resolveria. Submódulos e subtrees são para os casos em que não resolveria: código que não é publicado, que você altera junto com o projeto principal, ou que precisa ficar preso a um commit exato.

2. Submódulos

O que um submódulo realmente é

Um submódulo é um ponteiro de um repositório para um commit específico de outro. O repositório externo (o superprojeto) não contém os arquivos do interno. Ele contém duas coisas:

  1. Uma entrada de árvore de modo 160000 (um "gitlink") que guarda o id do commit interno.
  2. Um arquivo .gitmodules que diz de onde clonar.

Isto é o que git ls-tree -r HEAD imprimiu depois de adicionar um:

100644 blob 9b6e268...  .gitmodules
100644 blob b80f0bd...  app.txt
160000 commit 26f28f8...  vendor/lib

e o .gitmodules:

[submodule "vendor/lib"]
	path = vendor/lib
	url = ../lib

O repositório interno é um repositório Git normal; seus dados ficam em .git/modules/ do superprojeto, e o diretório de trabalho vendor/lib tem um arquivo .git apontando para lá.

Adicionando e clonando

$ git submodule add ../lib vendor/lib
$ git status --short
A  .gitmodules
A  vendor/lib
$ git commit -m "add lib"

Quando alguém clona o superprojeto, o diretório do submódulo fica vazio: o Git buscou o ponteiro, mas não os arquivos. No teste, o clone simples tinha 0 arquivos em vendor/lib e git submodule status mostrou um - na frente (não inicializado). Duas formas de obter o conteúdo:

git clone --recurse-submodules <url>          # all at once
# or, after a plain clone:
git submodule update --init --recursive

Depois disso o submódulo fica em um HEAD destacado exatamente no commit registrado ("HEAD detached at c30e138"). É de propósito: o superprojeto diz "preciso deste commit", não "preciso desta branch". Definir git config submodule.recurse true faz pull, checkout e outros comandos também atualizarem os submódulos; sem isso você precisa rodar git submodule update depois de trocar de branch ou puxar, senão os arquivos internos ficam no commit antigo.

Alterando o projeto interno

Para avançar o ponteiro, entre no submódulo, atualize e commite o novo ponteiro no repositório externo:

$ cd vendor/lib && git pull origin main     # the inner repo gets lib 3
$ cd ../..
$ git status --short
 M vendor/lib
$ git diff --submodule
Submodule vendor/lib c30e138..26f28f8:
  > lib 3
$ git add vendor/lib && git commit -m "bump lib"

Note que o repositório externo vê apenas "o ponteiro mudou". git diff --submodule (ou git config diff.submodule log) mostra os commits internos. Se você editar arquivos dentro do submódulo, precisa commitar e dar push no repositório interno primeiro, depois commitar o ponteiro no externo. Se você commitar o ponteiro e der push só no externo, todo mundo recebe um ponteiro para um commit que não existe no servidor, e o update deles falha. git push --recurse-submodules=check se recusa a enviar nessa situação, e =on-demand envia os internos por você. Defina push.recurseSubmodules=check para virar hábito.

Comandos do dia a dia

ComandoO que faz
git submodule statuso commit registrado de cada submódulo; - não inicializado, + difere do ponteiro, U conflito
git submodule update --init --recursivefaz checkout dos commits registrados, inclusive submódulos aninhados
git submodule update --remotevai para o commit mais recente da branch indicada em .gitmodules (branch = main)
git submodule foreach '<cmd>'roda um comando em cada um ($name, $sha1, $path estão disponíveis)
git submodule synccopia URLs alteradas de .gitmodules para sua configuração local

Removendo um submódulo

Não há um comando único. A sequência que funcionou:

git submodule deinit -f vendor/lib      # unregister it
git rm -f vendor/lib                    # remove the path and edit .gitmodules
rm -rf .git/modules/vendor/lib          # optional: delete the stored repository

Depois do git rm, o teste mostrou M .gitmodules e D vendor/lib, e o repositório interno continuou em .git/modules/ até ser apagado à mão.

Armadilhas

3. Subtrees

Um subtree copia os arquivos de outro repositório para um diretório seu e registra de onde vieram. Não há arquivo de ponteiro nem segundo repositório no disco: para todos os outros, os arquivos são arquivos comuns.

$ git subtree add --prefix=third_party/lib2 ../lib main --squash
Added dir 'third_party/lib2'
$ git log --oneline | head -3
739a047 Merge commit 'eb86450...' as 'third_party/lib2'
eb86450 Squashed 'third_party/lib2/' content from commit 26f28f8
0de6faf bump lib
$ git subtree pull --prefix=third_party/lib2 ../lib main --squash
Subtree is already at commit 26f28f8eb38ce39ffc30a227ab1288d645feaff1.

--squash condensa o histórico do outro projeto em um commit; deixe de fora para importar o histórico completo. git subtree push envia de volta ao repositório de origem suas mudanças locais naquele diretório, que é o recurso que torna subtrees úteis para código que você consome e também contribui.

SubmóduloSubtree
Os outros precisam rodar comandos extrassim (update --init)não
Preso a um commit exato da origemsim, por desenhopelo commit de merge que você fez
Tamanho do repositóriopequeno (só o ponteiro)contém o código (e o histórico, a menos que seja squash)
Editar a dependência no lugarpossível, mas dois repositórios para enviarfácil, um repositório; subtree push para a origem
Fácil ver "que versão é essa"git submodule statusler a mensagem do commit squash
Removervários passosgit rm -r do diretório
Ruído no históriconenhumcommits de merge e squash

Regra prática: submódulos quando a dependência é um projeto próprio e as pessoas devem tratá-la como somente leitura em uma versão fixa; subtrees quando você quer um checkout simples para todos, ou raramente a atualiza.

4. Worktrees

Um worktree é outro diretório de trabalho ligado ao mesmo repositório (mesmos objetos e branches). Ele substitui o hábito de clonar o repositório duas vezes, ou de usar stash, só para olhar uma segunda branch.

$ git worktree add ../app-wt -b feature/x
$ git worktree list
/work/app     739a047 [main]
/work/app-wt  739a047 [feature/x]
$ git worktree remove ../app-wt

Cada worktree tem sua própria branch em checkout, índice e arquivos não rastreados, e o Git se recusa a fazer checkout da mesma branch em dois worktrees. Use-os para rodar um build longo em uma branch enquanto corrige um bug em outra, para revisar um pull request sem mexer no seu trabalho, ou para comparar duas versões lado a lado. Também servem bem para vários agentes de IA ou jobs de CI trabalhando no mesmo repositório.

5. Tornando repositórios grandes manejáveis

Clone raso: git clone --depth 1 <url> baixa apenas o commit mais recente. O repositório de teste informou um commit e git rev-parse --is-shallow-repository devolveu true. É ideal para builds de CI que só precisam dos arquivos. Limites: comandos que dependem do histórico (log, blame, bisect, describe) veem só o que você tem; git fetch --unshallow traz o resto.

Clone parcial: git clone --filter=blob:none <url> baixa commits e árvores mas não o conteúdo dos arquivos; o Git busca um blob na primeira vez que precisa dele (checkout, diff, blame). Você mantém o histórico completo, com um primeiro download pequeno, e o remoto precisa suportar filtros (git config remote.origin.partialclonefilter mostrou blob:none). --filter=tree:0 dispensa também as árvores, para servidores de build que só querem commits recentes.

Sparse checkout: depois do clone, escolha quais diretórios aparecem no disco.

$ git sparse-checkout set --cone docs
$ ls
app.txt  docs
$ git sparse-checkout list
docs

O modo cone (o padrão nas versões recentes) é rápido e mantém os arquivos da raiz do repositório mais os diretórios que você lista. Combine com um clone parcial em um monorepo: git clone --filter=blob:none --sparse <url> e depois sparse-checkout set <dir>, assim você não baixa nem o histórico nem o conteúdo dos arquivos das outras equipes.

6. Git LFS (armazenamento de arquivos grandes)

O Git guarda toda versão de todo arquivo para sempre, então um binário de 200 MB editado dez vezes custa cerca de 2 GB em cada clone. O LFS troca arquivos grandes por um pequeno ponteiro de texto no repositório e guarda o conteúdo real em um servidor separado, baixado sob demanda.

git lfs install                  # once per machine
git lfs track "*.psd"            # writes the pattern into .gitattributes
git add .gitattributes design.psd

O que o Git guarda para um arquivo rastreado é um ponteiro assim:

version https://git-lfs.github.com/spec/v1
oid sha256:4d7a214614ab2935c943f9e0ff69d22eadbb8f32b1258daaa5e2ca24d17e2393
size 12345

O que saber: é preciso rodar git lfs track antes de adicionar os arquivos (senão entram como blobs normais, e movê-los depois significa reescrever o histórico com git lfs migrate); o serviço de hospedagem precisa suportar LFS e muitas vezes tem cotas de armazenamento e de banda; e um clone sem LFS instalado recebe só os arquivos de ponteiro. Código-fonte, texto e imagens pequenas não precisam dele.

7. Escolhendo

Diagram: Which Git tool for sharing or scaling

8. Erros comuns

  1. Clonar sem --recurse-submodules e estranhar a pasta vazia.
  2. Commitar o ponteiro de um submódulo antes de enviar o commit interno.
  3. Editar dentro de um submódulo com HEAD destacado e perder os commits ao trocar.
  4. Usar um submódulo para algo que um gerenciador de pacotes resolveria melhor.
  5. Usar git rm em um submódulo e esquecer .git/modules e .gitmodules.
  6. Usar clones rasos no CI e depois rodar ferramentas que precisam do histórico (git describe, geradores de changelog).
  7. Adicionar binários grandes ao Git antes de ativar o LFS, e depois tentar removê-los com um commit normal (eles ficam no histórico).
  8. Fazer checkout da mesma branch em dois worktrees (o Git recusa) ou apagar o diretório de um worktree à mão em vez de git worktree remove (rode git worktree prune).

9. O que mencionar em uma entrevista

Resumo rápido

Submódulo: ponteiro fixo para outro repositório, comandos extras para todos. Subtree: arquivos copiados, simples para os outros, histórico mais ruidoso. Worktree: várias branches em checkout a partir de um repositório. Raso, parcial e sparse: baixam menos histórico, menos conteúdo, menos arquivos. LFS: binários grandes como ponteiros. E muitas vezes a resposta certa é um pacote.

Fontes

Pratique este tema: DevOps & Cloud

Mais guias