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
| Necessidade | Ferramenta | Ideia |
|---|---|---|
| Usar o código de outro projeto em uma versão exata, mantendo-o como repositório separado | Submódulo | o 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 outros | Subtree | os arquivos viram arquivos comuns no seu repositório |
| Várias branches abertas ao mesmo tempo | Worktree | um repositório, vários diretórios de trabalho |
| Clonar mais rápido, com menos histórico | Clone raso (shallow) | só os últimos N commits |
| Clonar mais rápido, com menos conteúdo de arquivos | Clone parcial | blobs buscados quando necessários |
| Trabalhar em uma fatia de uma árvore grande | Sparse checkout | só alguns diretórios no disco |
| Arquivos binários grandes | Git LFS | o repositório guarda ponteiros pequenos; o conteúdo fica em outro lugar |
| Bibliotecas compartilhadas com versões | Um gerenciador de pacotes | nã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:
- Uma entrada de árvore de modo
160000(um "gitlink") que guarda o id do commit interno. - Um arquivo
.gitmodulesque 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
| Comando | O que faz |
|---|---|
git submodule status | o commit registrado de cada submódulo; - não inicializado, + difere do ponteiro, U conflito |
git submodule update --init --recursive | faz checkout dos commits registrados, inclusive submódulos aninhados |
git submodule update --remote | vai 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 sync | copia 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
- Esquecer de atualizar. Depois de
git pullo ponteiro se move mas os arquivos não, e o build roda código antigo. Usesubmodule.recurseou o hábito de atualizar após o merge. - Ponteiros para commits não enviados. Veja acima; use
--recurse-submodules=check. - Surpresas do HEAD destacado. Commits feitos em um submódulo destacado não pertencem a nenhuma branch; crie ou troque para uma branch antes de commitar.
- CI. A etapa de checkout precisa buscar os submódulos (
--recurse-submodules, ousubmodules: recursiveno GitHub Actions), e as credenciais do CI precisam poder ler os repositórios internos. - URLs relativas.
url = ../libsegue o remoto do próprio superprojeto, então um fork e o original resolvem corretamente; URLs absolutas fixam um servidor. - O protocolo file. Desde o Git 2.38.1, submódulos não podem ser clonados pelo transporte local
file://por padrão, uma correção de segurança (CVE-2022-39253). Experimentos locais precisam degit -c protocol.file.allow=always; projetos reais usam ssh ou https. - Conflitos de ponteiro. Se duas branches avançam o mesmo submódulo para commits diferentes, o Git reporta conflito no caminho; escolha o commit que quer com
git add vendor/libdepois de fazer checkout dele.
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ódulo | Subtree | |
|---|---|---|
| Os outros precisam rodar comandos extras | sim (update --init) | não |
| Preso a um commit exato da origem | sim, por desenho | pelo commit de merge que você fez |
| Tamanho do repositório | pequeno (só o ponteiro) | contém o código (e o histórico, a menos que seja squash) |
| Editar a dependência no lugar | possível, mas dois repositórios para enviar | fácil, um repositório; subtree push para a origem |
| Fácil ver "que versão é essa" | git submodule status | ler a mensagem do commit squash |
| Remover | vários passos | git rm -r do diretório |
| Ruído no histórico | nenhum | commits 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
- Clonar sem
--recurse-submodulese estranhar a pasta vazia. - Commitar o ponteiro de um submódulo antes de enviar o commit interno.
- Editar dentro de um submódulo com HEAD destacado e perder os commits ao trocar.
- Usar um submódulo para algo que um gerenciador de pacotes resolveria melhor.
- Usar
git rmem um submódulo e esquecer.git/modulese.gitmodules. - Usar clones rasos no CI e depois rodar ferramentas que precisam do histórico (
git describe, geradores de changelog). - 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).
- 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(rodegit worktree prune).
9. O que mencionar em uma entrevista
- Um submódulo é um gitlink (modo 160000) mais
.gitmodules: um ponteiro para um commit exato de outro repositório, em checkout como HEAD destacado. clone --recurse-submodules,submodule update --init --recursiveepush --recurse-submodules=check.- Submódulo versus subtree versus gerenciador de pacotes, com os trade-offs (custo de fluxo, fixação de versão, histórico, tamanho).
- Worktrees para branches em paralelo em um repositório.
- Clones rasos, parciais e sparse resolvem problemas diferentes: profundidade do histórico, conteúdo dos arquivos e arquivos no disco.
- O LFS guarda ponteiros no Git e o conteúdo em um servidor; configure antes de adicionar os arquivos.
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
- Scott Chacon e Ben Straub, Pro Git: Git Tools - Submodules.
- The Git project, documentação de git-submodule, gitsubmodules, git-worktree, git-sparse-checkout e partial clone.
- The Git project, git subtree (em
contrib/) e git-config paraprotocol.file.allow(a mudança do CVE-2022-39253 no Git 2.38.1). - Git LFS e sua especificação.
Pratique este tema: DevOps & Cloud