Git Submodule

O Que São Submódulos?

Submódulos são repositórios Git incluídos dentro de outro repositório Git. Eles permitem manter código externo como parte do seu projeto, mas mantendo seu histórico e gerenciamento separados.

Adicionando Um Submódulo

Para adicionar um submódulo ao seu projeto:

git submodule add [URL] [caminho]

Exemplo:

git submodule add https://github.com/usuario/biblioteca.git libs/biblioteca

Especificando Uma Branch

Para adicionar um submódulo e definir uma branch específica:

git submodule add -b [nome_da_branch] [URL] [caminho]

Exemplo:

git submodule add -b develop https://github.com/usuario/biblioteca.git libs/biblioteca

O Arquivo .gitmodules

O comando git submodule add cria ou atualiza automaticamente o arquivo .gitmodules no diretório raiz do seu projeto. Este arquivo rastreia os submódulos e suas configurações:

[submodule "libs/biblioteca"]
    path = libs/biblioteca
    url = https://github.com/usuario/biblioteca.git
    branch = develop  # Opcional, presente apenas se você especificar uma branch

Clonando Um Projeto Com Submódulos

Método 1: Clone Recursivo

git clone --recursive [URL-do-projeto]

Método 2: Clone Normal + Inicialização

git clone [URL-do-projeto]
cd [projeto]
git submodule init
git submodule update

Método 3: Comando Combinado

git clone [URL-do-projeto]
cd [projeto]
git submodule update --init

Tratando Submódulos Aninhados

Para inicializar e atualizar submódulos, incluindo submódulos aninhados (submódulos dentro de submódulos):

git submodule update --init --recursive

Atualizando Submódulos

Atualizar Um Submódulo Específico

cd [caminho-do-submódulo]
git pull origin [branch]
cd ..
git add [caminho-do-submódulo]
git commit -m "Atualizado submódulo para a última versão"

Atualizar Todos Os Submódulos Para as Últimas Versões

git submodule update --remote
git add .
git commit -m "Atualizados todos os submódulos para as últimas versões"

Verificando O Status Dos Submódulos

git submodule status

Removendo Um Submódulo

Remova o submódulo do arquivo .gitmodules:

git config -f .gitmodules --remove-section submodule.[caminho-do-submódulo]

Salve as alterações no .gitmodules:
```
git add .gitmodules
```

Remova a seção do submódulo da configuração do Git:

git config --remove-section submodule.[caminho-do-submódulo]

Remova o submódulo do staging:
```
git rm --cached [caminho-do-submódulo]
```

Comite as alterações:

git commit -m "Removido submódulo [nome-do-submódulo]"

Apague os arquivos do submódulo:

rm -rf [caminho-do-submódulo]
rm -rf .git/modules/[caminho-do-submódulo]

Boas Práticas

Especifique versões estáveis: Vincule submódulos a commits específicos ou tags para evitar problemas com atualizações não testadas.
Documente dependências: Mantenha uma lista clara de submódulos e suas funções no projeto.
Use submódulos com moderação: Submódulos adicionam complexidade - use apenas quando necessário.
Considere alternativas: Para projetos mais simples, dependências de pacotes (npm, pip, etc.) podem ser mais adequadas que submódulos.

Solução De Problemas Comuns

Submódulos Vazios

Se um submódulo aparecer como um diretório vazio:

git submodule update --init --recursive

Problemas De Detached HEAD

Se seu submódulo estiver em estado “detached HEAD”:

cd [caminho-do-submódulo]
git checkout [branch-desejada]

Erros Ao Clonar Submódulos

Se você encontrar erros de permissão ao clonar submódulos, verifique:

Suas credenciais de acesso ao repositório
Se o URL do submódulo está correto no arquivo .gitmodules

Grimorio Dev

Explorador