Skip to main content

Submodules | Git

  • Submodules | Git

O que é um Git Submodule?​

Um Git Submodule é uma forma de incluir um repositório Git dentro de outro repositório Git. Ele permite que você referencie um projeto externo (outro repositório) como parte do seu projeto principal, sem copiar o código para dentro do repositório principal.

🔧 Por que usar submodules?​

Você pode usar submodules quando:

  • Quer reutilizar código compartilhado entre diferentes projetos.
  • Precisa manter uma dependência externa fixa em uma versão específica, com controle total.
  • Está trabalhando com um monorepo leve, mas com separação clara entre projetos.
  • Deseja contribuir separadamente para o repositório principal e para o submódulo.

📦 Como funciona (por baixo dos panos)?​

  • Um submodule é basicamente uma referência (commit específico) para um repositório externo.
  • O repositório principal armazena essa referência num arquivo chamado .gitmodules e no index.
  • O submodule vive em uma pasta dentro do repositório principal, mas é tratado como um repositório independente.

🚀 Comandos principais​

1. Adicionar um submodule​

git submodule add https://github.com/usuario/repositorio caminho/para/submodulo

Isso cria a pasta, adiciona o submodule e registra em .gitmodules.

2. Clonar um projeto com submodules​

git clone --recurse-submodules <url>

Ou, se já clonou sem o --recurse-submodules:

git submodule update --init --recursive

3. Atualizar submodules​

git submodule update --remote

Esse comando busca a última versão do branch remoto definido para o submodule (útil se você quer "puxar" atualizações de dependências).

4. Remover um submodule​

É mais manual:

  • Remover entrada do .gitmodules
  • Remover entrada do .git/config
  • Remover a pasta do submodule
  • Remover do index:
git rm --cached caminho/para/submodulo

⚠️ Cuidados​

  • Submodules não acompanham automaticamente as mudanças feitas nos repositórios externos. É você quem precisa atualizar as referências manualmente.
  • Pode causar confusão se não for bem documentado ou se a equipe não tiver experiência com Git.
  • Em times grandes, pode ser melhor usar subtrees ou gerenciadores de dependência (como git sparse-checkout, NuGet, npm, etc.), dependendo do caso.

📘 Exemplo real​

Suponha que você tem um projeto chamado MinhaApp e quer incluir um repositório chamado BibliotecaDeUtilitarios.

git submodule add https://github.com/fulano/BibliotecaDeUtilitarios libs/Utils

Isso criará a pasta libs/Utils, registrará o repositório como submodule, e travará o commit atual. Você pode navegar até lá e usar git normalmente dentro dela.