O Que É um Git Submodule?

Um submodule é um repositório aninhado dentro de outro repositório, fixado em um commit específico, para que você possa incluir código externo enquanto rastreia sua versão exata.

Um submodule permite que um repositório Git contenha outro como um subdiretório, travado em um commit específico. É uma forma de reutilizar uma biblioteca ou componente compartilhado mantendo seu histórico separado e sua versão explícita. Submodules são poderosos, mas têm fama de surpreender quem está começando.

Como funcionam os submodules

O repositório pai armazena um ponteiro para um commit específico do submodule, não seus arquivos. O submodule vive em seu próprio repositório com seu próprio histórico. Quando você faz o checkout do pai em um dado commit, o commit registrado do submodule diz exatamente qual versão do código aninhado usar.

Adicionando e atualizando submodules

Você adiciona um submodule, depois o inicializa e atualiza para puxar o conteúdo do commit fixado.

git submodule add https://github.com/owner/lib.git vendor/lib
git submodule update --init --recursive

Por que podem ser complicados

Submodules adicionam etapas a fluxos de trabalho comuns. Um clone simples busca o pai, mas deixa os submodules vazios até você inicializá-los. Atualizar o ponteiro do submodule é um commit separado no pai. Esquecer essas etapas leva a arquivos ausentes ou dependências desatualizadas, uma fonte frequente de confusão.

Submodules em CI/CD

Um checkout de CI precisa ser instruído a buscar submodules, ou o build falhará com código ausente. A maioria das actions de checkout expõe uma opção de submodules para buscá-los, recursivamente se necessário. Como cada submodule é seu próprio clone, eles somam ao tempo de checkout e devem ser buscados apenas quando o build realmente depende deles.

Trabalhando com submodules

• Inicialize e atualize os submodules após clonar o pai.
• Faça commit no pai quando avançar um ponteiro de submodule.
• Habilite o checkout de submodules no CI ou o build ficará sem arquivos.
• Considere alternativas como gerenciadores de pacotes para reutilização mais simples.

Principais conclusões

• Um submodule aninha um repositório dentro de outro, fixado em um commit.
• Um clone simples deixa os submodules vazios até você inicializá-los.
• O CI precisa optar por buscar submodules ou os builds ficam sem seu código.

Guias relacionados