7.11 Git Tools - Submodules

De eenvoudigste werkwijze bij het gebruik van submodules in een project zou zijn als je eenvoudigweg een subproject naar binnentrekt en de updates ervan van tijd tot tijd binnen haalt maar waarbij je niet echt iets wijzigt in je checkout. Laten we een eenvoudig voorbeeld doornemen.

Als je wilt controleren voor nieuw werk in een submodule, kan je in de directory gaan en git fetch aanroepen en git merge gebruiken om de wijzigingen uit de branch stroomopwaarts in de lokale code in te voegen.

Als je nu teruggaat naar het hoofdproject en git diff --submodule aanroept kan je zien dat de submodule is bijgewerkt en je krijgt een lijst met commits die eraan is toegevoegd. Als je niet elke keer --submodule wilt intypen voor elke keer dat je git diff aanroept, kan je dit als standaard formaat instellen door de diff.submodule configuratie waarde op “log” te zetten.

Als je nu gaat committen zal je de nieuwe code in de submodule insluiten als andere mensen updaten.

Er is ook een makkelijker manier om dit te doen, als je er de voorkeur aan geeft om niet handmatig te fetchen en mergen in de subdirectory. Als je git submodule update --remote aanroept, zal Git naar je submodules gaan en voor je fetchen en updaten.

Dit commando zal standaard aannemen dat je de checkout wilt updaten naar de master-branch van de submodule repository. Je kunt dit echter naar iets anders wijzigen als je wilt. Bijvoorbeeld, als je de DbConnector submodule de “stable” branch van die repository wilt laten tracken, kan je dit aangeven in het .gitmodules bestand (zodat iedereen deze ook trackt), of alleen in je lokale .git/config bestand. Laten we het aangeven in het .gitmodules bestand:

Als je de -f .gitmodules weglaat, zal het de wijziging alleen voor jou gelden, maar het is waarschijnlijk zinvoller om die informatie bij de repository te tracken zodat iedereen dat ook zal gaan doen.

Als we nu git status aanroepen, zal Git ons laten zien dat we “new commits” hebben op de submodule.

Als je de configuratie instelling status.submodulessummary instelt, zal Git je ook een korte samenvatting van de wijzigingen in je submodule laten zien:

Als je op dit moment git diff aanroept kunnen we zien dat zowel we onze .gitmodules bestand hebben gewijzigd als dat daarbij er een aantal commmits is die we omlaag hebben gepulld en die klaar staan om te worden gecommit naar ons submodule project.

Dit is best wel handig omdat we echt de log met commits kunnen zien waarvan we op het punt staan om ze in onze submodule te committen. Eens gecommit, kan je deze informatie ook achteraf zien als je git log -p aanroept.

Git zal standaard proberen alle submodules te updaten als je git submodule update --remote aanroept, dus als je er hier veel van hebt, is het wellicht aan te raden om de naam van alleen die submodule door te geven die je wilt updaten.

Het is zeer waarschijnlijk dat als je submodules gebruikt, je dit zult doen omdat je echt aan de code in die submodule wilt werken tegelijk met het werken aan de code in het hoofdproject (of verspreid over verschillende submodules). Anders zou je waarschijnlijk een eenvoudiger afhankelijkheids-beheer systeem (dependency management system) hebben gebruikt (zoals Maven of Rubygems).

Dus laten we nu eens een voorbeeld behandelen waarin we gelijkertijd wijzigingen aan de submodule en het hoofdproject maken en deze wijzigingen ook gelijktijdig committen en publiceren.

Tot dusverre, als we het git submodule update commando aanriepen om met fetch wijzigen uit de repositories van de submodule te halen, ging Git de wijzigingen ophalen en de files in de subdirectory updaten, maar zou het de subdirectory in een staat laten die bekend staat als “detached HEAD”. Dit houdt in dat er geen lokale werk branch is (zoals “master”, bijvoorbeeld) waar de wijzigingen worden getrackt. Zonder een werkbranch waarin de wijzigingen worden getrackt, betekent het dat zelfs als je wijzigingen aan de submodule commit, deze wijzigingen waarschijnlijk verloren zullen gaan bij de volgende keer dat je git submodule update aanroept. Je zult een aantal extra stappen moeten zetten als je wijzigingen in een submodule wilt laten tracken.

Om de submodule in te richten zodat het eenvoudiger is om erin te werken, moet je twee dingen doen. Je moet in elke submodule gaan en een branch uitchecken om in te werken. Daarna moet je Git vertellen wat het moet doen als je wijzigingen hebt gemaakt en daarna zal git submodule update --remote nieuw werk van stroomopwaarts pullen. Je hebt nu de keuze om dit in je lokale werk te mergen, of je kunt proberen je nieuwe lokale werk te rebasen bovenop de nieuwe wijzigingen.

Laten we eerst in onze submodule directory gaan en een branch uitchecken.

Laten we het eens proberen met de “merge” optie. Om dit handmatig aan te geven kunnen we gewoon de --merge optie in onze update aanroep toevoegen. Hier zullen we zien dat er een wijziging op de server was voor deze submodule en deze wordt erin gemerged.

Als we in de DbConnector directory gaan, hebben we de nieuwe wijzigingen al in onze lokale stable-branch gemerged. Laten we nu eens kijken wat er gebeurt als we onze lokale wijziging maken aan de library en iemand anders pusht tegelijk nog een wijziging stroomopwaarts.

Als we nu onze submodule updaten kunnen we zien wat er gebeurt als we een lokale wijziging maken en er stroomopwaarts ook nog een wijziging is die we moeten verwerken.

Als je de --rebase of --merge bent vergeten, zal Git alleen de submodule updaten naar wat er op de server staat en je lokale project in een detached HEAD status zetten.

Maak je geen zorgen als dit gebeurt, je kunt eenvoudigweg teruggaan naar deze directory en weer je branch uitchecken (die je werk nog steeds bevat) en handmatig origin/stable mergen of rebasen (of welke remote branch je wilt).

Als je jouw wijzigingen aan je submodule nog niet hebt gecommit en je roept een submodule update aan die problemen zou veroorzaken, zal Git de wijzigingen ophalen (fetchen) maar het nog onbewaarde werk in je submodule directory niet overschrijven.

Als je wijzigingen hebt gemaakt die conflicteren met wijzigingen die stroomopwaarts zijn gemaakt, zal Git je dit laten weten als je de update uitvoert.

Je kunt in de directory van de submodule gaan en de conflicten oplossen op dezelfde manier zoals je anders ook zou doen.

We hebben nu een aantal wijzigingen in onze submodule directory. Sommige van deze zijn van stroomopwaarts binnengekomen via onze updates en andere zijn lokaal gemaakt en zijn nog voor niemand anders beschikbaar omdat we ze nog niet hebben gepusht.

Als we het hoofdproject committen en deze pushen zonder de submodule wijzigingen ook te pushen, zullen andere mensen die willen zien wat onze wijzigingen inhouden problemen krijgen omdat er voor hen geen enkele manier is om de wijzigingen van de submodule te pakken te krijgen waar toch op wordt voortgebouwd. Deze wijzigingen zullen alleen in onze lokale kopie bestaan.

Om er zeker van te zijn dat dit niet gebeurt, kan je Git vragen om te controleren dat al je submodules juist gepusht zijn voordat het hoofdproject wordt gepusht. Het git push commando leest het --recurse-submodules argument die op de waardes “check” of “on-demand” kan worden gezet. De “check” optie laat een push eenvoudigweg falen als een van de gecomitte submodule wijzigingen niet is gepusht.

Zoals je kunt zien, geeft het ook wat behulpzame adviezen over wat we vervolgens kunnen doen. De eenvoudige optie is om naar elke submodule te gaan en handmatig naar de remotes te pushen om er zeker van te zijn dat ze extern beschikbaar zijn en dan deze push nogmaals te proberen.

De andere optie is om de “on-demand” waarde te gebruiken, wat zal proberen dit voor je te doen.

Zoals je hier kunt zien, ging Git in de DbConnector module en heeft deze gepusht voordat het hoofdproject werd gepusht. Als die push van de submodule om wat voor reden ook faalt, zal de push van het hoofdproject ook falen. Je kunt dit gedrag de standaard maken door git config push.recurseSubmodules on-demand te doen.

Als je een submodule-referentie wijzigt op hetzelfde moment als een ander, kan je in enkele problemen geraken. In die zin, dat wanneer submodule histories uitelkaar zijn gaan lopen en naar uitelkaar lopende branches in het superproject worden gecommit, zal het wat extra werk van je vergen om dit te repareren.

Als een van de commits een directe voorouder is van de ander (een fast-forward merge), dan zal git eenvoudigweg de laatste voor de merge kiezen, dus dat werkt prima.

Git zal echter niet eens een triviale merge voor je proberen. Als de submodule commits uiteen zijn gaan lopen en ze moeten worden gemerged, zal je iets krijgen wat hier op lijkt:

Dus wat er hier eigenlijk gebeurd is, is dat Git heeft achterhaald dat de twee branches punten in de historie van de submodule hebben opgeslagen die uiteen zijn gaan lopen en die gemerged moeten worden. Het legt dit uit als “merge following commits not found” (merge volgend op commits niet gevonden), wat verwarrend is, maar we leggen zo uit waarom dit zo is.

Om dit probleem op te lossen, moet je uit zien te vinden in welke staat de submodule zou moeten zijn. Vreemdgenoeg geeft Git je niet echt veel informatie om je hiermee te helpen, niet eens de SHA-1 getallen van de commits van beide kanten van de historie. Gelukkig is het redelijk eenvoudig om uit te vinden. Als je git diff aanroept kan je de SHA-1 getallen van de opgeslagen commits krijgen uit beide branches die je probeerde te mergen.

Dus in dit geval, is eb41d76 de commit in onze submodule die wij hebben en c771610 is de commit die stroomopwaarts aanwezig is. Als we naar onze submodule directory gaan, moet het al aanwezig zijn op eb41d76 omdat de merge deze nog niet zal hebben aangeraakt. Als deze om welke reden dan ook er niet is, kan je eenvoudigweg een branch die hiernaar wijst aanmaken en uit checken.

Wat nu een belangrijke rol gaat spelen is de SHA-1 van de commit van de andere kant. Dit is wat je in zult moeten mergen en oplossen. Je kunt ofwel de merge met de SHA-1 gewoon proberen, of je kunt een branch hiervoor maken en dan deze proberen te mergen. We raden het laatste aan, al was het maar om een mooier merge commit bericht te krijgen.

Dus, we gaan naar onze submodule directory, maken een branch gebaseerd op die tweede SHA-1 van git diff en mergen handmatig.

We hebben een echte merge conflict, dus als we deze oplossen en committen, kunnen we eenvoudigweg het hoofdproject updaten met het resultaat.

Dit kan nogal verwarrend overkomen, maar het is niet echt moeilijk.

Interessant genoeg, is er een ander geval die Git aankan. Als er een merge commit bestaat in de directory van de submodule die beide commits in z’n historie bevat, zal Git je deze voorstellen als mogelijke oplossing. Het ziet dat op een bepaald punt in het submodule project iemand branches heeft gemerged met daarin deze twee commits, dus wellicht wil je die hebben.

Dit is waarom de foutboodschap van eerder “merge following commits not found” was, omdat het dit niet kon doen. Het is verwarrend omdat, wie verwacht er nu dat Git dit zou proberen?

Als het een enkele acceptabele merge commit vindt, zal je iets als dit zien:

Wat hier gesuggereerd wordt om te doen is om de index te updaten alsof je git add zou hebben aangeroepen, wat het conflict opruimt, en dan commit. Echter, je moet dit waarschijnlijk niet doen. Je kunt net zo makkelijk naar de directory van de submodule gaan, kijken wat het verschil is, naar deze commit fast-forwarden, het goed testen en daarna committen.

Dit bereikt hetzelfde, maar op deze manier kan je verfiëren dat het werkt en je hebt de code in je submodule als je klaar bent.

Er is een foreach submodule commando om een willekeurig commando aan te roepen in elke submodule. Dit kan echt handig zijn als je een aantal submodules in hetzelfde project hebt.

Bijvoorbeeld, stel dat we een nieuwe functie willen beginnen te maken of een bugfix uitvoeren en we hebben werkzaamheden in verscheidene submodules onderhanden. We kunnen eenvoudig al het werk in al onze submodules stashen.

Daarna kunnen we een nieuwe branch maken en ernaar switchen in al onze submodules.

Je ziet waar het naartoe gaat. Een heel nuttig ding wat je kunt doen is een mooie unified diff maken van wat er gewijzigd is in je hoofdproject alsmede al je subprojecten.

Hier kunnen we zien dat we een functie aan het definieren zijn in een submodule en dat we het in het hoofdproject aanroepen. Dit is overduidelijk een versimpeld voorbeeld, maar hopelijk geeft het je een idee van hoe dit handig kan zijn.

Je wilt misschien een aantal aliassen maken voor een aantal van deze commando’s, omdat ze redelijk lang kunnen zijn en je geen configuratie opties voor de meeste van deze kunt instellen om ze standaard te maken. We hebben het opzetten van Git aliassen in Git aliassen behandeld, maar hier is een voorbeeld van iets wat je misschien zou kunnen opzetten als je van plan bent veel met submodules in Git te werken.

Op deze manier kan je eenvoudig git supdate aanroepen als je je submodules wilt updaten, of git spush om te pushen met controle op afhankelijkheden op de submodule.