7.11 Ferramentas do Git - Submódulos

O modelo mais simples de se usar submódulos em um projeto seria se você simplesmente estivesse consumindo um subprojeto e quisesse obter atualizações dele de vez em quando mas não estivesse na verdade modificando nada no seu checkout. Vamos passar por um exemplo simples disso.

Se você quiser checar se há novos trabalhos em um submódulo, você pode entrar no diretório e rodar git fetch e fazer git merge da branch de upstream para atualizar o código local.

Agora, se você voltar ao projeto principal e rodar git diff --submodule, você pode ver que o submódulo foi atualizado e obter uma lista de commits que foram adicionados a ele. Se você não quer digitar --submodule toda vez que você roda git diff, você pode defini-lo como formato padrão setando o valor de config diff.submodule como “log”.

Se você comitar nesse ponto então você vai travar o submódulo para ter o novo código quando as outras pessoas atualizarem.

Existe também uma maneira mais fácil de fazer isso, caso você prefira não fazer o fetch e o merge manualmente no subdiretório. Se você rodar git submodule update --remote, o Git vai entrar nos seus submódulos e fazer fetch e update para você.

Este comando vai por padrão assumir que você quer atualizar o checkout para a branch padrão do repositório do submódulo remoto (aquela apontada pelo HEAD no remoto). Você pode, no entanto, mudar isso para algo diferente se você quiser. Por exemplo, se você quer que o submódulo DbConnector rastreie a branch “stable” daquele repositório, você pode configurá-lo tanto no seu arquivo .gitmodules (para que todos os outros também o rastreiem), quanto apenas no seu arquivo local .git/config. Vamos defini-lo no arquivo .gitmodules:

Se você omitir o -f .gitmodules ele fará a alteração apenas para você, mas provavelmente faz mais sentido rastrear essa informação junto ao repositório para que todos os outros também a tenham.

Quando rodamos git status neste ponto, o Git nos mostrará que temos “new commits” no submódulo.

Se você definir a configuração status.submodulesummary, o Git também mostrará a você um curto sumário das alterações aos seus submódulos:

A este ponto se você rodar git diff nós podemos ver tanto que nós modificamos nosso arquivo .gitmodules quanto que há uma quantidade de commits que nós baixamos e que estão prontos para o commit em nosso projeto submódulo.

Isso é bem bacana pois nós podemos ver, na prática, o log dos commits que estamos prestes a comitar no nosso submódulo. Uma vez comitado, você pode ver esta informação depois do fato também quando você roda git log -p.

O Git tentará, por padrão, atualizar todos os seus submódulos quando você rodar git submodule update --remote. Se você tiver muitos deles, você pode querer passar o nome de apenas o submódulo que você quer tentar atualizar.

Vamos agora nos colocar no lugar do seu colaborador, que tem seu próprio clone local do repositório MainProject. Simplesmente executar git pull para pegar suas alterações recém-comitadas não é o bastante:

Por padrão, o comando git pull faz o fetch recursivo de alterações de submódulos, conforme podemos ver na saída do primeiro comando acima. Entretanto, ele não atualiza (update) os submódulos. Isso é mostrado pela saída do comando git status, a qual mostra que o submódulo está modificado (“modified”), e que possui novos commits (“new commits”). Além do mais, os parênteses exibindo os novos commits apontam para a esquerda (<), indicando que estes commits estão registrados no MainProject mas não estão presentes no checkout local do DbConnector. Para finalizar a atualização, você precisa rodar o git submodule update:

Note que, para estar mais seguro, você deveria rodar git submodule update com a flag --init caso os commits do MainProject de que você acabou de dar pull tenham adicionado novos submódulos, e com a flag --recursive caso algum submódulo tenha submódulos aninhados.

Se você quiser automatizar esse processo, você pode adicionar a flag --recurse-submodules ao comando git pull (desde o Git 2.14). Isto fará com que o Git rode git submodule update logo após o pull, colocando os submódulos no estado correto. Ainda mais, se você deseja fazer com que o Git sempre dê pull com --recurse-submodules, você pode configurar a opção submodule.recurse como true (isso funciona para o git pull a partir do Git 2.15). Esta opção vai fazer o Git usar a flag --recurse-submodules para todos os comandos que lhe derem suporte (exceto clone).

Existe uma situação especial que pode acontecer ao se puxar atualizações do superprojeto: poderia ser que o repositório upstream mudou a URL do submódulo no arquivo .gitmodules em um dos commits de que você deu pull. Isso pode ocorrer por exemplo se o projeto do submódulo mudar sua plataforma de hospedagem. Nesse caso, é possível para o git pull --recurse-submodules, ou git submodule update, falhar caso o superprojeto faça referência a um commit do submódulo não encontrado no remoto do submódulo configurado localmente em seu repositório. A fim de remediar essa situação, o comando git submodule sync se faz necessário:

É bem provável que se você está usando submódulos, você esteja fazendo isso porque você realmente quer trabalhar no código dentro do submódulo ao mesmo tempo em que está trabalhando no código dentro do projeto principal (ou ao longo de vários submódulos). De outro modo, você estaria provavelmente, ao invés disso, usando um sistema de gerenciamento de dependências mais simples (como Maven ou Rubygems).

Então agora vamos prosseguir com um exemplo de fazer alterações no submódulo ao mesmo tempo que no projeto principal e comitar e publicar (publish) essas alterações todas juntas.

Até agora, quando rodamos o comando git submodule update para fazer o fetch das alterações a partir dos repositórios dos submódulos, o Git traria as alterações e atualizaria os arquivos no subdiretório mas deixaria o sub-repositório no que se chama de estado de “detached HEAD” (HEAD separado). Isto significa que não há nenhuma branch local de trabalho (como master, por exemplo) rastreando alterações. Sem uma branch de trabalho rastreando alterações, isso significa que mesmo se você comitar alterações para o submódulo, as ditas alterações serão bem possivelmente perdidas da próxima vez que você rodar um git submodule update. Você tem que executar alguns passos extras se quiser que alterações num submódulo sejam rastreadas.

A fim de configurar o seu submódulo para ser mais fácil de se entrar e codar nele, você precisa fazer duas coisas. Você precisa entrar em cada submódulo e fazer o checkout de uma branch para se trabalhar. Aí você precisa contar ao Git o que fazer se você tiver feito alterações e mais tarde git submodule update --remote puxar um novo trabalho do upstream. As opções são de que você pode fazer um merge delas no seu trabalho local, ou você pode tentar fazer o rebase do seu trabalho local em cima das novas alterações.

Primeiro de tudo, vamos entrar no nosso diretório de submódulo e fazer checkout de uma branch.

Vamos tentar atualizar o nosso submódulo com a opção de merge (opção “merge”). Para especificá-la de forma manual, podemos apenas adicionar a opção --merge à nossa chamada do comando update. Aqui veremos que houve uma alteração no servidor para este submódulo e ela sofre merge.

Se formos para dentro do diretório DbConnector, teremos as novas alterações já mescladas (merged) em nossa branch stable local. Agora vamos ver o que acontece quando fazemos nossa própria alteração local para a biblioteca e alguma outra pessoa faz push de uma outra mudança para o upstream, tudo ao mesmo tempo.

Agora, se atualizarmos nosso submódulo, podemos ver o que acontece quando tivermos feito uma alteração local e o upstream também tiver uma mudança que precisamos incorporar.

Se você se esquecer de --rebase ou --merge, o Git vai só atualizar o submódulo para aquilo que se encontre no servidor e resetar seu projeto para o estado detached HEAD.

Caso isso aconteça, não se preocupe, você pode simplesmente retornar ao diretório e dar checkout da sua branch de novo (a qual continuará contendo o seu trabalho) e aplicar um merge ou um rebase com origin/stable (ou qualquer outro branch remoto que você quiser) manualmente.

Se você não tiver comitado suas modificações em seu submódulo e você rodar um submodule update que possa causar problemas, o Git irá buscar (fetch) as modificações, contudo, sem sobrescrever qualquer trabalho que não tenha sido salvo, dentro do diretório de seu submódulo.

Se as alterações que você realizou conflitarem com algo que mudou no upstream, o Git irá informá-lo quando você rodar o update.

Você pode ir para o diretório de submódulo e resolver o conflito, exatamente como você faria normalmente.

Agora, nós temos algumas modificações no nosso diretório de submódulo. Algumas delas foram trazidas desde o upstream através de nossos updates, já outras foram criadas localmente e ainda não estão à disposição de qualquer outra pessoa, uma vez que ainda não realizamos o push.

Se nós dermos um commit no projeto principal e aplicarmos o push nele sem aplicar o push às modificações do submódulo juntas, as outras pessoas, ao tentarem realizar check out em nossas alterações, vão ter problemas, visto que elas não possuirão meio de obter aquelas atualizações do submódulo, das quais elas dependem. Aquelas alterações, as do submódulo, só existirão na nossa cópia local.

Para ter a certeza que isto não ocorra, você tem de pedir que o Git verifique, previamente à submissão do projeto principal, se em todos os seus submódulos foi aplicado o push corretamente. O comando git push pode ser acompanhado pelo argumento --recurse-submodules o qual pode assumir valores como: “check” ou “on-demand”. A opção “check” fará push simplesmente falhar se alguma alteração commitada no submódulo ainda não tiver sido enviada por push.

Como você pode ver, ele também oferece orientações úteis sobre o que fazer em seguida. A opção simples consiste em adentrar cada submódulo e, manualmente, realizar push nos remotes para nos certificar que tais submódulos estarão disponíveis de maneira externa e, então, tentar efetuar esse push novamente. Se você desejar que o comportamento verificado em “check” suceda em todo e qualquer push, você pode deixá-lo como o comportamento padrão mediante este comando git config push.recurseSubmodules check.

A outra opção compreende a utilização do valor “on-demand”, que tentará executar as ações anteriores por você.

Dali, pelo que você foi capaz de ver, o Git foi ao módulo DbConnector e ali aplicou o push antes de dar push no projeto central. Se esse push no submódulo vier a falhar em razão de algum motivo, o push do projeto pai vai também falhar. É possível deixar esse procedimento de modo default, fazendo git config push.recurseSubmodules on-demand.

Se você alterar uma referência de submódulo ao mesmo tempo que outra pessoa, poderá encontrar alguns problemas. Isso quer dizer: se as histórias do submódulo divergiram e os commits acompanharam essas ramificações, que divergem, em superprojetos; vai ser preciso um pouco de trabalho, de sua parte, com vistas a reparar isto.

Se um dos commits for ancestral direto do outro (um merge fast-forward), o Git simplesmente escolherá o segundo para o merge, e tudo funcionará bem.

Com isso, o Git não intentará mesmo num tipo banal de merging a seu dispor. Se os commits no submódulo divergirem e precisarem que lhes faça um merge, você terá algo semelhante a isto, como resposta:

Em suma: o que aconteceu, aqui, é que o Git imaginou que ambas the branches registraram pontos da história do submódulo que são incompatíveis e cujas pontas hão de ser amarradas, via um merge. Ele explica o problema como “merge following commits not found”, o que é confuso, mas logo explicaremos o motivo.

De modo a solucionar esse imbróglio, você terá de descobrir em qual estado o seu submódulo deveria estar. Estranhamente, o Git não fornece muitas informações úteis aqui, nem mesmo os SHA-1s dos commits dos dois lados do histórico. Felizmente, é simples descobri-los. Se você submeter o comando git diff, poderá extrair os SHA-1s, dos commits anotados nos dois branches nos quais tem buscado realizar a fusão (merge).

Em sendo assim, neste caso, eb41d76 é o commit em nosso submódulo que nós possuíamos e c771610 é aquele commit que o upstream tinha. Se entrarmos no diretório do submódulo, ele já deverá estar em eb41d76, pois o merge não o teria alterado. Por outro lado, caso não seja, você poderá apenas criar um branch, apontando em direção dele e então submeter um checkout logo a seguir.

O que importa é o que se tira do SHA-1 de autoria do commit que vêm da parte que nos é oposta. É isso que você precisará mesclar e resolver. Você pode simplesmente tentar o merge diretamente com o SHA-1 ou criar um branch para ele e então tentar mesclá-lo. Sugerimos a segunda opção, ainda que seja apenas para produzir uma mensagem de commit de merge melhor.

Assim, entraremos no diretório do submódulo, criaremos um branch chamado “try-merge” com base no segundo SHA-1 de git diff e faremos o merge manualmente.

Encontramos um conflito de merge real; se o resolvermos e fizermos seu commit, poderemos simplesmente atualizar o projeto principal com o resultado.

Isso pode parecer um pouco confuso, mas na verdade não é muito difícil.

Curiosamente, há outro caso que o Git consegue tratar. Se houver no diretório do submódulo um commit de merge cujo histórico contenha ambos os commits, o Git o sugerirá como possível solução. Ele percebe que, em algum ponto do projeto do submódulo, alguém mesclou branches que continham esses dois commits; talvez seja esse o resultado que você queira.

É por isso que a mensagem de erro anterior era “merge following commits not found”: o Git não conseguiu fazer isso. É confuso, pois quem esperaria que ele sequer tentasse fazer isso?

Se ele encontrar um único commit de merge aceitável, você verá algo assim:

O comando sugerido pelo Git atualizará o index como se você tivesse executado git add (o que elimina o conflito) e então fará o commit. No entanto, provavelmente você não deveria fazer isso. É igualmente fácil entrar no diretório do submódulo, examinar a diferença, fazer fast-forward para esse commit, testá-lo corretamente e então fazer o commit.

Isso alcança o mesmo resultado, mas dessa forma você ao menos pode verificar que tudo funciona e, ao terminar, terá o código no diretório do submódulo.

Há um comando de submódulo foreach para rodar algum comando arbitrário em cada submódulo. Isso pode ser realmente útil se você tem um número de submódulos no mesmo projeto.

Por exemplo, digamos que nós queiramos iniciar um novo recurso ou fazer uma correção de bug e nós temos trabalhos ocorrendo em vários submódulos. Podemos facilmente fazer stash de todo o trabalho em todos os submódulos.

Então nós podemos criar uma nova branch e mudar para ela em todos os nossos submódulos.

Você entendeu a ideia. Uma coisa realmente útil que você pode fazer é produzir um diff unificado do que foi alterado em seu projeto principal e todos os seus subprojetos também.

Aqui nós podemos ver que estamos definindo uma função num submódulo e a chamando no projeto principal. Isso é, obviamente, um exemplo simplificado, mas esperançosamente te dá uma ideia de como isso pode ser útil.

Você pode querer configurar alguns apelidos (aliases) para alguns destes comandos dado que eles podem ser muito grandes e não é possível configurar opções para a maioria deles a fim de os tornarem padrões. Abordamos a configuração de aliases do Git em Aliases (Apelidos) no Git, mas aqui está um exemplo do que você talvez queira configurar se pretende trabalhar muito com submódulos no Git.

Dessa forma, você pode simplesmente executar git supdate quando quiser atualizar seus submódulos ou git spush para fazer push com verificação das dependências de submódulos.

Por exemplo, alternar entre branches que contêm submódulos também pode ser complicado em versões do Git anteriores à 2.13. Se você criar um novo branch, adicionar um submódulo nele e então voltar para um branch sem esse submódulo, o diretório do submódulo permanecerá como um diretório não rastreado:

Remover o diretório não é difícil, mas pode ser um pouco confuso vê-lo ali. Se você o remover e depois voltar para o branch que contém o submódulo, precisará executar submodule update --init para preenchê-lo novamente.

Novamente, não é realmente difícil, mas pode ser um pouco confuso.

Nas versões contemporâneas da ferramenta (Git >= 2.13), toda esta gama de ações encontrou simplificação diante do acréscimo de --recurse-submodules, como flag a acompanhar o comando git checkout; a incumbência dessa se dá por repousar os submódulos ao estado ideal àquele correspondente no ramo que então tencionamos.

Usar a flag --recurse-submodules de git checkout também pode ser útil quando você trabalha em vários branches do superprojeto e, em cada um deles, o submódulo aponta para commits diferentes. De fato, se você alternar entre branches que registram o submódulo em commits diferentes, ao executar git status o submódulo aparecerá como “modified” e indicará “new commits”. Atribui-se isso ao fato de, como padrão, o submódulo ser preterido quanto a acompanhamento de trânsito ao flutuarmos nestes ramos.

Isso pode ser muito confuso, portanto é uma boa ideia sempre usar git checkout --recurse-submodules quando o projeto contém submódulos. Em versões antigas do Git que não possuem a flag --recurse-submodules, você pode usar git submodule update --init --recursive depois do checkout para colocar os submódulos no estado correto.

Felizmente, você pode instruir o Git (>=2.14) a sempre usar a flag --recurse-submodules definindo a opção de configuração submodule.recurse: git config submodule.recurse true. Como observado acima, isso também fará o Git percorrer recursivamente os submódulos em todo comando que possua a opção --recurse-submodules (exceto git clone).

Outra ressalva importante que muitas pessoas encontram envolve a mudança de subdiretórios para submódulos. Se você rastreava arquivos no projeto e quer movê-los para um submódulo, deve ter cuidado, ou o Git ficará irritado com você. Suponha que existam arquivos em um subdiretório do projeto e que você queira transformá-lo em um submódulo. Se excluir o subdiretório e então executar submodule add, o Git reclamará:

Primeiro, você precisa retirar o diretório CryptoLibrary da área de preparação. Depois, poderá adicionar o submódulo:

Agora suponha que você tenha feito isso em um branch. Se tentar voltar para um branch em que esses arquivos ainda estejam na árvore real, e não em um submódulo, receberá este erro:

Você pode forçar a mudança com checkout -f, mas tome cuidado para não ter alterações não salvas ali, pois esse comando poderá sobrescrevê-las.

Então, ao voltar, por algum motivo você encontrará um diretório CryptoLibrary vazio, e talvez nem git submodule update consiga corrigi-lo. Pode ser necessário entrar no diretório do submódulo e executar git checkout . para recuperar todos os arquivos. Você pode executar isso em um script submodule foreach para aplicá-lo a vários submódulos.

É importante observar que, hoje em dia, os submódulos mantêm todos os dados Git no diretório .git do projeto principal; portanto, ao contrário de versões muito antigas do Git, destruir o diretório de um submódulo não fará você perder commits ou branches.

Com essas ferramentas, os submódulos podem ser um método bastante simples e eficaz para desenvolver simultaneamente vários projetos relacionados, mas ainda separados.