Um submódulo Git é um repositório independente mantido dentro de um diretório de outro repositório. O projeto principal registra o identificador de um commit do submódulo. Isso permite usar uma versão específica da dependência e preservar o histórico dela separado do histórico principal.
O que o repositório principal registra
O arquivo .gitmodules associa o caminho do submódulo ao endereço usado para obter seu repositório. A referência ao commit fica numa entrada especial do Git chamada de gitlink. O principal registra essa referência no lugar de incorporar cada arquivo do submódulo ao próprio histórico.
Numa atualização, o diretório do submódulo precisa conter o commit que o principal indica. O comportamento padrão de git submodule update faz esse checkout com HEAD destacado, ou seja, posicionado num commit sem uma branch local ativa. Para desenvolver dentro do submódulo, você precisa conferir a branch de trabalho adequada.
Uma correção numa biblioteca
Num exemplo didático, uma aplicação usa uma biblioteca no diretório libs/calculos, registrado como submódulo. A correção de uma função é gravada num commit do repositório da biblioteca. Depois, o principal registra o novo identificador para que outro clone use essa revisão da biblioteca.
Um commit criado apenas na máquina local pode deixar o principal apontando para uma revisão que os demais clones não conseguem obter. A publicação da biblioteca e a permissão de acesso ao seu repositório precisam permitir a recuperação do commit referenciado. Publicar o principal não envia automaticamente os commits do submódulo.
Obter os arquivos após o clone
A partir da raiz de um projeto já clonado, este comando inicializa os submódulos e obtém os commits registrados, incluindo os submódulos aninhados:
git submodule update --init --recursiveA execução bem-sucedida preenche os diretórios com as revisões indicadas pelo projeto. Ela não seleciona automaticamente a versão mais recente de cada biblioteca. Para conferir o resultado, use git submodule status: a saída informa o commit e o caminho de cada submódulo. Um sinal + indica que o commit presente difere do registrado pelo principal. O sinal - indica um submódulo ainda não inicializado.
Dúvidas frequentes
Perguntas frequentes sobre submódulo
- Editar um arquivo do submódulo cria um commit no principal?
- A edição altera o diretório de trabalho do submódulo e ainda precisa ser registrada no histórico dele. O repositório principal registra separadamente a referência ao commit selecionado.
- Clonar o principal preenche os submódulos?
- Um clone comum pode deixar os diretórios dos submódulos sem conteúdo. Você pode incluir --recurse-submodules no clone para obtê-los ou executar git submodule update --init --recursive num projeto já clonado.
- O submódulo acompanha automaticamente a versão mais recente?
- O principal registra um commit específico. Buscar uma versão mais recente e selecionar esse commit no submódulo ainda exige registrar a referência atualizada no principal para reproduzir a mudança.
Para continuar
Recursos relacionados
Documentação
Pro Git: submódulos
O capítulo do Pro Git explica a inclusão de submódulos, o clone e a atualização das referências entre os repositórios.
Abrir recursoSite de referência
DevSide: desenvolvimento colaborativo
Orientação ao vivo para conferir alterações no submódulo e a referência que o repositório principal registra.
Abrir recursoAplicação na formação
Vibe Coding: Do Zero ao MVP
Ao revisar alterações num projeto com submódulos, você precisa conferir o commit da dependência e a referência registrada no repositório principal.
Conhecer a formação
Fontes consultadas
Referências deste verbete
Este verbete ajudou você?
Obrigado pela resposta. Ela fica salva apenas neste navegador.