7.11 Git Tools - Submodules

Die eenvoudigste model vir die gebruik van submodules in 'n projek sal wees as jy net 'n subprojek verbruik en van tyd tot tyd opdaterings daaruit wil kry, maar nie regtig iets in jou checkout wysig nie. Kom ons stap deur 'n eenvoudige voorbeeld daarvan.

As jy wil kyk vir nuwe werk in 'n submodule, kan jy in die gids ingaan en git fetch uitvoer en git merge op die stroomopwaartse tak doen om die plaaslike kode by te werk.

Nou as jy teruggaan na die hoofprojek en git diff --submodule uitvoer, kan jy sien dat die submodule opgedateer is en 'n lys kry van vasleggings wat daaraan bygevoeg is. As jy nie --submodule elke keer as jy git diff uitvoer wil intik nie, kan jy dit as die verstekformaat stel deur die diff.submodule konfigurasiewaarde op “log” te stel.

As jy op hierdie punt vaslê, sal jy die submodule sluit (lock) sodat dit die nuwe kode het wanneer ander mense opdateer.

Daar is ook 'n makliker manier om dit te doen, as jy verkies om nie met die hand af te haal en te smelt in die subgids nie. As jy git submodule update --remote uitvoer, sal Git in jou submodules ingaan en namens jou afhaal en opdateer.

Hierdie opdrag sal by verstek aanneem dat jy die checkout wil opdateer na die verstektak van die afgeleë submodule-bewaarplek (die een waarna HEAD op die remote wys). Jy kan dit egter stel op iets anders as jy wil. Byvoorbeeld, as jy wil hê die DbConnector submodule moet daardie bewaarplek se “stable” tak naspoor, kan jy dit stel in óf jou .gitmodules lêer (sodat almal anders dit ook naspoor), óf net in jou plaaslike .git/config lêer. Kom ons stel dit in die .gitmodules lêer:

As jy die -f .gitmodules weglaat sal dit net die verandering vir jou maak, maar dit maak waarskynlik meer sin om daardie inligting saam met die bewaarplek te spoor sodat almal dit ook doen.

Wanneer ons op hierdie punt git status uitvoer, sal Git vir ons wys dat ons “new commits” (nuwe vasleggings) op die submodule het.

As jy die konfigurasie-instelling status.submodulesummary stel, sal Git ook vir jou 'n kort opsomming van veranderings aan jou submodules wys:

As jy op hierdie oomblik git diff uitvoer, kan ons sien dat ons beide ons .gitmodules lêer gewysig het en ook dat daar 'n aantal vasleggings is wat ons ingetrek het en gereed is om na ons submodule-projek vas te lê.

Dit is nogal oulik aangesien ons regtig die log van vasleggings kan sien wat ons op die punt is om na ons submodule vas te lê. Sodra dit vasgelê is, kan jy hierdie inligting ook agterna sien wanneer jy git log -p uitvoer.

Git sal by verstek probeer om al jou submodules op te dateer wanneer jy git submodule update --remote uitvoer. As jy baie daarvan het, sal jy dalk die naam wil deurgee van slegs die submodule wat jy wil probeer opdateer.

Kom ons plaas ons nou in die skoene van jou medewerker, wat hul eie plaaslike kloon van die MainProject-bewaarplek het. Om bloot git pull uit te voer om jou nuut-vasgelegde veranderings te kry, is nie genoeg nie:

By verstek haal die git pull opdrag rekursief submoduleveranderings af (fetch), soos ons in die afvoer van die eerste opdrag hierbo kan sien. Dit dateer egter nie die submodules op nie. Dit word getoon deur die afvoer van die git status opdrag, wat wys dat die submodule “modified” is, en “new commits” het. Wat meer is, die hakies wat die nuwe vasleggings wys, wys na links (<), wat aandui dat hierdie vasleggings in MainProject opgeteken is, maar nie teenwoordig is in die plaaslike DbConnector checkout nie. Om die opdatering te finaliseer, moet jy git submodule update uitvoer:

Let daarop dat jy om aan die veilige kant te wees, git submodule update met die --init vlag moet uitvoer vir ingeval die MainProject-vasleggings wat jy so pas ingetrek het nuwe submodules bygevoeg het, en met die --recursive vlag indien enige submodules geneste submodules het.

As jy hierdie proses wil outomatiseer, kan jy die --recurse-submodules vlag by die git pull opdrag voeg (sedert Git 2.14). Dit sal Git git submodule update dadelik ná die pull laat uitvoer en die submodules in die regte toestand plaas. Boonop, as jy wil hê dat Git altyd moet intrek met --recurse-submodules, kan jy die konfigurasie-opsie submodule.recurse stel na true (dit werk vir git pull sedert Git 2.15). Hierdie opsie sal maak dat Git die --recurse-submodules vlag gebruik vir alle opdragte wat dit ondersteun (behalwe clone).

Daar is 'n spesiale situasie wat kan gebeur wanneer superprojekopdaterings ingetrek word: dit kan wees dat die stroomopwaartse bewaarplek die URL van die submodule in die .gitmodules lêer in een van die vasleggings wat jy intrek verander het. Dit kan byvoorbeeld gebeur as die submoduleprojek sy gasheerplatform verander. In daardie geval is dit moontlik dat git pull --recurse-submodules, of git submodule update, misluk as die superprojek verwys na 'n submodule-vaslegging wat nie gevind word in die submodule se remote soos plaaslik in jou bewaarplek opgestel is nie. Om hierdie situasie reg te stel, word die git submodule sync opdrag benodig:

Dit is hoogs waarskynlik dat as jy submodules gebruik, jy dit doen omdat jy regtig aan die kode in die submodule wil werk terwyl jy aan die kode in die hoofprojek (of oor verskeie submodules heen) werk. Andersins sou jy waarskynlik eerder 'n eenvoudiger afhanklikheidsbestuurstelsel (dependency management system soos Maven of Rubygems) gebruik het.

Kom ons gaan nou deur 'n voorbeeld waar ons gelyktydig veranderings aan die submodule asook aan die hoofprojek maak, en daardie veranderings terselfdertyd vaslê en publiseer.

Tot dusver, wanneer ons die git submodule update opdrag uitgevoer het om veranderings van die submodule-bewaarplekke te haal, het Git die veranderings gekry en die lêers in die subgids opgedateer, maar sal die sub-bewaarplek agterlaat in 'n sogenaamde “detached HEAD” toestand. Dit beteken dat daar geen plaaslike werktak (soos master byvoorbeeld) is wat veranderings naspoor nie. Sonder 'n werktak wat veranderings naspoor, beteken dit dat selfs as jy veranderings na die submodule vaslê, sal daardie veranderings heel moontlik verlore raak die volgende keer as jy git submodule update uitvoer. Jy moet 'n paar ekstra stappe doen as jy wil hê dat veranderings in 'n submodule nagespoor moet word.

Om jou submodule so op te stel dat dit makliker is om daarin te gaan en te kap, moet jy twee dinge doen. Jy moet in elke submodule ingaan en 'n tak uittrek om aan te werk. Dan moet jy vir Git vertel wat om te doen as jy veranderings gemaak het en later git submodule update --remote nuwe werk van stroomop intrek. Die opsies is dat jy dit in jou plaaslike werk kan insmelt (merge), of jy kan probeer om jou plaaslike werk bo-op die nuwe veranderings te rebase.

Kom ons gaan eerstens in ons submodule-gids in en trek 'n tak uit.

Kom ons probeer ons submodule opdateer met die “merge” opsie. Om dit handmatig te spesifiseer, kan ons bloot die --merge opsie by ons update oproep voeg. Hier sal ons sien dat daar 'n verandering op die bediener vir hierdie submodule was en dit word ingesmelt.

As ons in die DbConnector gids ingaan, is die nuwe veranderings reeds in ons plaaslike stable tak ingesmelt. Kom ons kyk nou wat gebeur wanneer ons ons eie plaaslike verandering aan die biblioteek maak en iemand anders op dieselfde tyd nog 'n verandering stroomopwaarts push.

As ons nou ons submodule opdateer, kan ons sien wat gebeur wanneer ons 'n plaaslike verandering aangebring het en daar stroomop ook 'n verandering is wat ons moet inkorporeer.

As jy die --rebase of --merge vergeet, sal Git bloot die submodule opdateer na wat ook al op die bediener is en jou projek terugstel na 'n "detached HEAD"-toestand.

As dit gebeur, moenie bekommerd wees nie, jy kan eenvoudig teruggaan in die gids en weer jou tak uittrek (wat steeds jou werk sal bevat) en met die hand origin/stable (of watter afgeleë tak jy ook al wil hê) insmelt of rebase.

As jy nie jou veranderings in jou submodule vasgelê het nie en jy voer 'n submodule update uit wat probleme sou veroorsaak, sal Git die veranderings afhaal, maar nie ongestoorde werk in jou submodulegids oorskryf nie.

As jy veranderings gemaak het wat in stryd is met iets wat stroomopwaarts verander is, sal Git jou laat weet wanneer jy die opdatering uitvoer.

Jy kan in die submodule-gids ingaan en die konflik regmaak soos jy normaalweg sou doen.

Nou het ons 'n paar veranderings in ons submodule-gids. Sommige hiervan is van stroomop deur ons opdaterings ingebring en ander is plaaslik gemaak en is nog nie aan enigiemand anders beskikbaar nie aangesien ons dit nog nie gepush het nie.

As ons in die hoofprojek vaslê en dit push sonder om ook die submoduleveranderings op te push, gaan ander mense wat ons veranderings probeer uittrek, in die moeilikheid wees, want hulle sal geen manier hê om die submoduleveranderings te kry waarvan afhanklik is nie. Daardie veranderings sal slegs op ons plaaslike kopie bestaan.

Om seker te maak dat dit nie gebeur nie, kan jy Git vra om te kyk dat al jou submodules behoorlik gepush is voordat jy die hoofprojek push. Die git push opdrag neem die --recurse-submodules argument wat gestel kan word na óf “check” óf “on-demand”. Die “check” opsie sal maak dat push eenvoudig misluk as enige van die vasgelegde submoduleveranderings nie gepush is nie.

Soos jy kan sien, gee dit vir ons ook nuttige raad oor wat ons volgende sal wil doen. Die eenvoudige opsie is om in elke submodule in te gaan en met die hand na die remotes te push om seker te maak dat hulle ekstern beskikbaar is, en dan hierdie push weer te probeer. As jy wil hê dat die “check” gedrag vir alle pushes moet plaasvind, kan jy hierdie gedrag die verstek maak deur git config push.recurseSubmodules check uit te voer.

Die ander opsie is om die “on-demand” waarde te gebruik, wat dit vir jou sal probeer doen.

Soos jy daar kan sien, het Git na die DbConnector module gegaan en dit gepush voor die hoofprojek gepush is. As daardie submodule-push vir een of ander rede misluk, sal die hoofprojek-push ook misluk. Jy kan hierdie gedrag as die verstelling maak deur git config push.recurseSubmodules on-demand te doen.

As jy 'n submodule-verwysing gelyktydig met iemand anders verander, kan jy dalk in 'n paar probleme vasloop. Dit wil sê, as die submodule geskiedenisse uiteengegaan het (diverged) en aan uiteenlopende takke in 'n superprojek vasgelê is, kan dit 'n bietjie werk verg vir jou om reg te maak.

As een van die vasleggings 'n direkte voorouer van die ander is ('n fast-forward saamsmelting), sal Git eenvoudig die laaste vir die saamsmelting kies, so dit werk goed.

Git sal egter nie eers 'n triviale saamsmelting vir jou probeer nie. As die submodule-vasleggings uiteenloop en saamgesmelt moet word, sal jy iets kry wat soos volg lyk:

So basies wat hier gebeur het, is dat Git uitgevind het dat die twee takke punte in die submodule se geskiedenis aanteken wat uiteenlopend is en saamgesmelt moet word. Dit verduidelik dit as “merge following commits not found”, wat verwarrend is, maar ons sal oor 'n rukkie verduidelik hoekom dit so is.

Om die probleem op te los, moet jy uitvind in watter toestand die submodule behoort te wees. Vreemd genoeg gee Git jou nie regtig veel inligting om te help nie, selfs nie die SHA-1’s van die vasleggings van albei kante van die geskiedenis nie. Gelukkig is dit maklik om uit te vind. As jy git diff uitvoer, kan jy die SHA-1’s kry van die vasleggings wat aangeteken is in beide takke wat jy probeer saamsmelt het.

In hierdie geval is eb41d76 die vaslegging in ons submodule wat ons gehad het, en c771610 is die vaslegging wat stroomopwaarts (upstream) was. As ons by ons submodulegids ingaan, behoort dit reeds op eb41d76 te wees, aangesien die samesmelting dit nie sou geraak het nie. As dit om een ​​of ander rede nie is nie, kan jy eenvoudig 'n tak skep en onttrek wat daarna verwys.

Wat belangrik is, is die SHA-1 van die vaslegging van die ander kant af. Dit is wat jy sal moet insmelt en oplos. Jy kan net die saamsmelting met die SHA-1 direk probeer, of jy kan 'n tak daarvoor skep en dan daardie een probeer insmelt. Ons beveel laasgenoemde aan, selfs net om 'n mooier samesmeltingsboodskap te maak.

So, ons sal na ons submodulegids gaan, 'n tak met die naam “try-merge” skep gebaseer op daardie tweede SHA-1 van git diff, en handmatig saamsmelt.

Ons het hier 'n werklike samesmeltingskonflik gekry, dus as ons dit oplos en vaslê, kan ons die hoofprojek bloot bywerk met die resultaat.

Dit mag 'n bietjie verwarrend wees, maar dit is nie regtig te moeilik nie.

Interessant genoeg is daar 'n ander scenario wat Git hanteer. As daar 'n samesmeltingsvaslegging in die submodulegids is wat beide vasleggings in sy geskiedenis bevat, sal Git dit as 'n moontlike oplossing vir jou voorstel. Dit sien dat iemand iewers in die submoduleprojek takke saamgesmelt het wat hierdie twee vasleggings bevat, sodat jy miskien daardie een wil hê.

Dit is hoekom die foutboodskap vroeër was “merge following commits not found”, aangesien dit nie dit kon doen nie. Dit is verwarrend, want wie sou verwag het dat dit dit sou probeer doen?

As dit wel 'n enkele aanvaarbare samesmeltingsvaslegging vind, sal jy iets soos volg sien:

Die voorgestelde opdrag wat Git verskaf, sal die indeks opdateer asof jy git add uitgevoer het (wat die konflik verwyder), en dan vaslê. Jy moet dit waarskynlik egter nie doen nie. Jy kan net so maklik na die submodulegids gaan, sien wat die verskil is, met fast-forward na hierdie vaslegging versnel, dit deeglik toets, en dit dan vaslê.

Dit bereik dieselfde doel, maar op hierdie manier kan jy ten minste verifieer dat dit werk en het jy die kode in jou submodulegids wanneer jy klaar is.

Daar is 'n foreach submodule opdrag om enige willekeurige opdrag in elke submodule uit te voer. Dit kan regtig baie nuttig wees as jy 'n aantal submodules in dieselfde projek het.

Byvoorbeeld, gestel ons wil 'n nuwe funksionaliteit begin of 'n foutsuiwering (bugfix) doen, en ons het werk aan die gang in verskeie submodules. Ons kan maklik al die werk in al ons submodules wegbêre (stash).

Dan kan ons 'n nuwe tak skep en na dit in al ons submodules oorslaan.

Jy verstaan die idee. Een regtig nuttige ding wat jy kan doen, is om 'n oulike verenigde verskil (unified diff) van wat verander het in jou hoofprojek en al jou subprojekte asook voor te berei.

Hier kan ons sien dat ons 'n funksie in 'n submodule definieer en dit in die hoofprojek oproep. Dit is natuurlik 'n vereenvoudigde voorbeeld, maar hopelik gee dit jou 'n idee van hoe dit nuttig mag wees.

Jy mag dalk wil oorweeg om sekere aliassen op te stel vir sommige van hierdie opdragte aangesien hulle redelik lank kan wees en jy nie konfigurasieopsies vir meeste van hulle kan stel om as verstekwaardes te dien nie. Ons het gehandel oor die opstel van Git-aliassen in Git-aliasse, maar hier is 'n voorbeeld van wat jy dalk wil opstel as jy van plan is om baie met submodules in Git te werk.

Op hierdie manier kan jy net git supdate uitvoer wanneer jy jou submodules wil opdateer, of git spush om te push terwyl daar vir afhanklikhede van submodules gekontroleer word.

Byvoorbeeld, die verandering van takke met submodules daarin kan ook moeilik wees met Git-weergawes ouer as Git 2.13. As jy 'n nuwe tak skep, 'n submodule byvoeg, en dan terugverander na 'n tak sonder daardie submodule, bly jou submodulegids steeds daar as 'n ongeregistreerde (untracked) gids:

Dit is nie moeilik om die gids te verwyder nie, maar dit kan 'n bietjie verwarrend wees om dit daar in te hê. As jy dit wel verwyder en dan terugwissel na die tak wat daardie submodule het, sal jy submodule update --init moet laat loop om dit te herbevolk.

Weereens, nie werklik moeilik nie, maar dit kan 'n bietjie verwarrend wees.

Nuwer weergawes van Git (Git >= 2.13) vereenvoudig alles deur die --recurse-submodules vlag by die git checkout opdrag by te voeg, wat sorg dra om die submodules in die regte toestand te plaas vir die tak waarna ons oorskakel.

Die gebruik van die --recurse-submodules vlag met git checkout kan ook nuttig wees as jy aan verskeie takke werk binne die superprojek, waar elkeen van jou submodules na verskillende vasleggings wys. Inderdaad, as jy oorskakel tussen takke wat na die submodule in verskillende vasleggings wys, sal die submodule in git status as “modified” vertoon word, asook “new commits” aandui. Dit is omdat die submodule se toestand by verstek nie oorgedra word by die oorskakeling na ander takke nie.

Dit kan baie verwarrend wees, so dit is 'n goeie idee om altyd git checkout --recurse-submodules te gebruik as jou projek submodules het. By ouer weergawes van Git, wat nie die --recurse-submodules vlag het nie, kan jy na die "checkout", git submodule update --init --recursive gebruik om die submodules weer reg in hul korrekte toestand te plaas.

Gelukkig kan jy vir Git (>=2.14) sê om altyd die --recurse-submodules vlag te gebruik deur die konfigurasie-opsie submodule.recurse in te stel: git config submodule.recurse true. Soos hierbo genoem, sal dit Git ook in submodules in laat afdaal vir elke opdrag wat 'n --recurse-submodules opsie het (behalwe git clone).

Die ander hoofstrik waarin mense trap behels die skakeling van subgidse na submodules. As jy lêers in jou projek genaspoor het en jy hulle nou in 'n submodule wil plaas, moet jy versigtig wees anders gaan Git met jou ontevrede wees. Neem aan dat jy lêers in 'n subgids in jou projek het, en jy wil dit na 'n submodule verander. As jy die subgids verwyder en dan submodule add uitvoer, raas Git met jou:

Jy moet eers die voorbereiding (staging) van die CryptoLibrary subgids ophef. Dan kan jy die submodule byvoeg:

Gestel nou jy het dit in 'n tak gedoen. As jy poog om terug te skakel na 'n tak waar daardie lêers steeds in die werklike boom (tree) is eerder as 'n submodule, sal jy hierdie fout ontvang:

Jy kan dit forseer om oor te slaan na daardie tak toe met checkout -f, maar pasop dat jy nie nog-ongestoorde werk daarbinne het nie aangesien dit oorgeskryf kan word met hierdie opdrag.

Dan, as jy weer teruggaan, kry jy om die een of ander rede 'n leë CryptoLibrary subgids en git submodule update herstel dit dalk ook nie. Jy mag dalk self binne die betrokke submodulegids moet inbeweeg en git checkout . daar uitvoer om al jou lêers weer terug te kan verkry. Jy kan dalk dink om eerder dit deur 'n submodule foreach draaiboekie (script) uit te voer wat dit weereens vir verskeie submodules self sal verrig.

Dit is belangrik om op te merk dat in deesdae se submodules, hulle al hul Git data stoor in die boonste projek se .git gids, so in teendeel as met baie ou weergawes van Git sal jy geen vasleggings of takke van 'n submodule kan kwytraak by die verwydering van daardie submodulegids nie.

Submodules met hierdie nutsgoed is nogal 'n vereenvoudigde en doeltreffende oplossing by die saamomgewing om in 'n verskeidenheid afsonderlike verhoudings of interafhanklike maar afsonderlike projekte terselfdertyd mee te werk.