Submódulos: Conceito central, fluxos de trabalho e dicas

Primeiro, quero apresentar uma breve explicação de um conceito central sobre submódulos que vai facilitar o trabalho com eles.

Os submódulos são rastreados pelo commit exato especificado no projeto pai, não uma ramificação, uma referência ou qualquer outra referência simbólica.

Eles nunca são atualizados automaticamente quando o repositório especificado pelo submódulo é atualizado, somente quando o próprio projeto pai é atualizado. Conforme expresso com clareza no capítulo Pro Git mencionado antes:

Ou, em outras palavras:

Ao lembrar esse conceito central e refletir sobre ele, você pode entender que o submódulo suporta bem alguns fluxos de trabalho e outros com uma otimização menor. Existem pelo menos três cenários em que os submódulos são uma escolha justa:

• Quando um componente ou subprojeto está mudando muito rápido ou as próximas mudanças vão quebrar a API, você pode bloquear o código para um commit específico para sua própria segurança.

• Quando você tem um componente que não é atualizado com muita frequência e quer rastrear este componente como uma dependência do fornecedor. É o que eu faço para meus plugins vim, por exemplo.

• Quando você está delegando uma parte do projeto a um terceiro e quer integrar o trabalho deles em um horário ou versão específico. De novo: funciona quando as atualizações não são muito frequentes.

Créditos ao finch pelos cenários bem explicados.

A infraestrutura do submódulo é poderosa e permite a separação e integração úteis de bases de código. No entanto, existem operações simples que não têm um procedimento simplificado ou um forte suporte à interface do usuário da linha de comando.

Se você usa submódulos git em seu projeto, já os encontrou ou vai encontrar. Quando acontecer, você vai ter que procurar a solução. Várias e várias vezes. Vou economizar seu tempo de pesquisa: Instapaper, Evernote ou coloque esta página nos favoritos à moda antiga (:D:D) e você vai estar preparado por um bom tempo.

Então, aqui está o que eu tenho para você:

Este é um fluxo de trabalho muito comum: você começa a usar o projeto de outra pessoa como submódulo, mas depois de um tempo encontra a necessidade de fazer personalizações e ajustes por conta própria, então quer bifurcar o projeto e substituir o submódulo por sua própria bifurcação. Mas como?

Os submódulos são armazenados em .gitmodules:

Você pode simplesmente editar o url com um editor de texto e executar o seguinte:

Essa ação atualiza o .git/config, que contém uma cópia desta lista de submódulos (você também pode editar a seção [submodule] relevante do .git/config manualmente).

Referência do Stack Overflow

É uma necessidade bastante comum, mas tem um procedimento um pouco complexo. Para remover um submódulo, você precisa:

1. Exclua a linha relevante do arquivo .gitmodules.

2. Exclua a seção relevante de .git/config.

3. Execute git rm --cached path_to_submodule (sem barra).

4. Faça o commit e exclua os arquivos de submódulo agora não rastreados.

Referência do Stack Overflow

Ou, em outras palavras, como faço para desfazer o submódulo git? Se tudo o que você quer é colocar o código do submódulo no repositório principal, só precisa remover o submódulo e adicionar mais uma vez os arquivos ao repositório principal:

1. Exclua a referência ao submódulo do índice, mas mantenha os arquivos:

2. Exclua o arquivo .gitmodules ou, se você tiver mais de um submódulo, edite este arquivo removendo o submódulo da lista:

3. Remova a pasta de metadados .git (verifique se você tem backup disso):

4. Adicione o submódulo ao índice do repositório principal:

NOTA: O procedimento descrito acima é destrutivo para o histórico do submódulo, nos casos em que você quer manter um histórico congruente de seus submódulos, você deve trabalhar com um "merge" sofisticado. Para mais informações, eu indico uma referência do Stack Overflow muito completa.

Às vezes, os submódulos podem ficar sujos sozinhos. Por exemplo, se você usar submódulos git para rastrear seus plugins vim, eles podem gerar ou modificar arquivos locais como helptags. É chato, mas o git status vai começar a incomodar você com essas alterações, mesmo que não esteja interessado nelas e não tenha intenção de fazer commit delas.

A solução é muito simples. Abra o arquivo .gitmodules na raiz do repositório e para cada submódulo que você quer ignorar, adicione ignore = dirty, como neste exemplo:

Obrigado a Nils pela ótima explicação.

Como o Git Submodule Tutorial no kernel.org nos lembra, há algumas coisas importantes a serem observadas ao interagir com os repositórios remotos.

A primeira é sempre publicar a alteração do submódulo antes de publicar a alteração no superprojeto que faz referência a ele. É uma abordagem fundamental, pois pode impedir que outras pessoas clonem o repositório.

A segunda é sempre lembrar de confirmar todas as alterações antes de executar git submodule update já que, se houver alterações, elas vão ser substituídas!

Armado com essas notas, você deve ser capaz de lidar com muitos fluxos de trabalho recorrentes comuns que surgem ao usar submódulos. Em um texto futuro, vou escrever sobre alternativas ao submódulo git.

Siga as minhas publicações em @durdn e a incrível equipe do @Bitbucket para arrasar no DVCS.