7.11 Git-verktyg - Undermoduler

Den enklaste modellen för att använda undermoduler i ett projekt är när du bara konsumerar ett underprojekt och vill få uppdateringar från det då och då, utan att själv ändra något i din utläggning. Låt oss gå igenom ett enkelt exempel.

Om du vill kontrollera om det finns nytt arbete i en undermodul kan du gå in i katalogen och köra git fetch och git merge mot uppströmsgrenen för att uppdatera den lokala koden.

Om du nu går tillbaka till huvudprojektet och kör git diff --submodule kan du se att undermodulen uppdaterades och få en lista över incheckningarna som lades till. Om du inte vill skriva --submodule varje gång du kör git diff kan du sätta det som standardformat genom att sätta konfigurationsvärdet diff.submodule till “log”.

Om du checkar in vid det här laget kommer du att låsa undermodulen till den nya koden när andra uppdaterar.

Det finns även ett enklare sätt om du föredrar att inte uppdatera och sammanfoga manuellt i underkatalogen. Om du kör git submodule update --remote kommer Git att gå in i dina undermoduler, uppdatera och växla åt dig.

Det här kommandot antar som standard att du vill uppdatera utläggningen till standardgrenen på fjärrkodförrådet för undermodulen (den som pekas ut av HEAD i fjärrkodförrådet). Du kan dock ställa in detta till något annat om du vill. Om du till exempel vill att undermodulen DbConnector ska spåra kodförrådets “stable”‑gren kan du ställa in det antingen i .gitmodules‑filen (så att alla andra också spårar det) eller bara i din lokala .git/config‑fil. Låt oss ställa in det i .gitmodules‑filen:

Om du lämnar bort -f .gitmodules görs ändringen bara lokalt, men det är oftast rimligare att spåra den informationen i kodförrådet så att alla andra gör det också.

När vi kör git status vid det här laget visar Git att vi har “new commits” i undermodulen.

Om du ställer in konfigurationen status.submodulesummary kommer Git också att visa en kort sammanfattning av ändringarna i dina undermoduler:

Om du kör git diff nu ser vi både att .gitmodules har ändrats och att det finns flera incheckningar som vi har uppdaterat och är redo att checka in i vårt undermodulsprojekt.

Det här är rätt kul eftersom vi faktiskt kan se loggen över incheckningarna som vi håller på att checka in i vår undermodul. När det är checkat in kan du se informationen i efterhand också när du kör git log -p.

Git försöker som standard uppdatera alla dina undermoduler när du kör git submodule update --remote. Om du har många kan du vilja skicka namnet på just den undermodul du vill uppdatera.

Låt oss nu kliva in i din kollegas skor, som har sin egen lokala klon av MainProject‑kodförrådet. Att bara köra git pull för att få dina nyincheckade ändringar räcker inte:

Som standard uppdaterar kommandot git pull undermoduländringar rekursivt, vilket vi ser i utdata från det första kommandot ovan. Det uppdaterar däremot inte undermodulerna. Detta visas av git status, som visar att undermodulen är “modified” och har “new commits”. Dessutom pekar klamrarna som visar nya incheckningar åt vänster (<), vilket betyder att dessa incheckningar är registrerade i MainProject men saknas i den lokala utläggningen av DbConnector. För att slutföra uppdateringen måste du köra git submodule update:

Observera att du för säkerhets skull bör köra git submodule update med flaggan --init ifall MainProject‑incheckningarna du just drog in lade till nya undermoduler, och med flaggan --recursive om några undermoduler har inbäddade undermoduler.

Om du vill automatisera processen kan du lägga till flaggan --recurse-submodules till git pull (sedan Git 2.14). Det gör att Git kör git submodule update direkt efter uppdatering, så att undermodulerna hamnar i rätt läge. Dessutom, om du vill att Git alltid ska dra med --recurse-submodules, kan du sätta konfigurationsalternativet submodule.recurse till true (detta fungerar för git pull sedan Git 2.15). Alternativet får Git att använda flaggan --recurse-submodules för alla kommandon som stöder det (utom clone).

Det finns en särskild situation som kan inträffa när du drar uppdateringar i överprojektet: det kan vara så att uppströmskodförrådet har ändrat URL:en till undermodulen i .gitmodules‑filen i någon av incheckningarna du drar in. Det kan till exempel hända om undermodulsprojektet byter värdplattform. I så fall är det möjligt att git pull --recurse-submodules, eller git submodule update, misslyckas om överprojektet refererar till en undermoduls‑incheckning som inte finns i det fjärrkodförråd som är konfigurerat lokalt i ditt kodförråd. För att rätta till detta krävs kommandot git submodule sync:

Det är ganska sannolikt att om du använder undermoduler så gör du det för att du verkligen vill arbeta med koden i undermodulen samtidigt som du arbetar med koden i huvudprojektet (eller över flera undermoduler). Annars skulle du förmodligen använda ett enklare beroendehanteringssystem (som Maven eller Rubygems).

Låt oss nu gå igenom ett exempel där vi gör ändringar i undermodulen samtidigt som huvudprojektet och checkar in och publicerar dessa ändringar samtidigt.

Hittills, när vi kört git submodule update för att uppdatera ändringar från undermodulkodförråden, har Git uppdaterat ändringarna och uppdaterat filerna i underkatalogen men lämnat underkodförrådet i ett så kallat "frikopplat HEAD"‑läge. Det betyder att det inte finns någon lokal arbetsgren (som till exempel master) som spårar ändringar. Utan en arbetsgren som spårar ändringar betyder det att även om du checkar in ändringar i undermodulen kan de mycket väl gå förlorade nästa gång du kör git submodule update. Du behöver ta några extra steg om du vill att ändringar i en undermodul ska spåras.

För att göra undermodulen lättare att gå in och hacka i behöver du göra två saker. Du behöver gå in i varje undermodul och växla till en gren att arbeta på. Sedan behöver du tala om för Git vad den ska göra om du har gjort ändringar och senare kör git submodule update --remote som drar in nytt arbete från uppströms. Alternativen är att du kan sammanfoga dem med ditt lokala arbete, eller försöka ombasera ditt lokala arbete ovanpå de nya ändringarna.

Låt oss först gå in i vår undermodulkatalog och växla till en gren.

Låt oss försöka uppdatera vår undermodul med “merge”‑alternativet. För att ange det manuellt kan vi helt enkelt lägga till flaggan --merge till vårt update‑anrop. Här ser vi att det fanns en ändring på servern för undermodulen och den sammanfogas in.

Om vi går in i katalogen DbConnector har vi de nya ändringarna redan sammanfogade i vår lokala stable‑gren. Låt oss nu se vad som händer när vi gör en egen lokal ändring i biblioteket och någon annan samtidigt skickar upp en annan ändring uppströms.

Om vi nu uppdaterar vår undermodul kan vi se vad som händer när vi har gjort en lokal ändring och uppströms också har en ändring som vi behöver ta in.

Om du glömmer --rebase eller --merge kommer Git bara uppdatera undermodulen till det som finns på servern och återställa ditt projekt till ett frikopplat HEAD‑läge.

Om detta händer behöver du inte oroa dig; du kan helt enkelt gå tillbaka in i katalogen och växla till din gren igen (som fortfarande innehåller ditt arbete) och sammanfoga eller ombasera origin/stable (eller vilken fjärrgren du vill) manuellt.

Om du inte har checkat in dina ändringar i undermodulen och kör en submodule update som skulle orsaka problem kommer Git att uppdatera ändringarna men inte skriva över osparat arbete i undermodulens katalog.

Om du gjorde ändringar som kolliderar med något som ändrats uppströms kommer Git att säga till när du kör uppdateringen.

Du kan gå in i undermodulkatalogen och lösa konflikten precis som vanligt.

Nu har vi några ändringar i undermodulkatalogen. Vissa av dessa drogs in uppströms via våra uppdateringar och andra gjordes lokalt och är inte tillgängliga för någon annan ännu eftersom vi inte har skickat upp dem.

Om vi checkar in i huvudprojektet och skickar upp det utan att också skicka undermoduländringarna hamnar andra som försöker växla till våra ändringar i problem, eftersom de inte har något sätt att få tagg i undermoduländringarna som de är beroende av. Dessa ändringar finns bara i vår lokala kopia.

För att vara säker på att detta inte händer kan du be Git kontrollera att alla dina undermoduler har skickats upp ordentligt innan du skickar upp huvudprojektet. Kommandot git push tar argumentet --recurse-submodules, som kan sättas till antingen “check” eller “on-demand”. Alternativet “check” gör att uppskickningen helt enkelt misslyckas om någon av de checkade in undermoduländringarna inte har skickats upp.

Som du ser ger den också råd om vad du kan göra härnäst. Det enkla alternativet är att gå in i varje undermodul och manuellt skicka till fjärrkodförråden för att se till att de är externt tillgängliga och sedan försöka skicka igen. Om du vill att beteendet “check” ska gälla för alla uppskick kan du göra detta till standard genom git config push.recurseSubmodules check.

Det andra alternativet är att använda värdet “on-demand”, som försöker göra detta åt dig.

Som du ser gick Git in i DbConnector‑modulen och skickade upp den innan den skickade upp huvudprojektet. Om uppskicket av undermodulen misslyckas av någon anledning kommer uppskicket av huvudprojektet också att misslyckas. Du kan göra detta till standardbeteende genom git config push.recurseSubmodules on-demand.

Om du ändrar en undermodulreferens samtidigt som någon annan kan du stöta på problem. Det vill säga, om undermodulhistorikerna har glidit isär och är checkade in till divergerande grenar i ett överprojekt kan det krävas lite arbete för att rätta till.

Om en av incheckningarna är en direkt anfader till den andra (en snabbspolningssammanfogning) väljer Git helt enkelt den senare, så det fungerar fint.

Git försöker dock inte ens göra en trivial sammanslagning åt dig. Om undermodulsincheckningarna glider isär och behöver sammanfogas får du något som ser ut så här:

I praktiken har Git alltså listat ut att de två grenarna pekar på punkter i undermodulens historik som har glidit isär och behöver sammanfogas. Den beskriver det som “merge following commits not found”, vilket är förvirrande, men vi förklarar varför om en stund.

För att lösa problemet behöver du ta reda på vilket läge undermodulen ska hamna i. Konstigt nog ger Git dig inte så mycket information här, inte ens SHA‑1‑värdena för incheckningarna på båda sidor. Lyckligtvis är det enkelt att ta reda på. Om du kör git diff kan du få SHA‑1‑värdena för incheckningarna som är registrerade i båda grenarna du försökte sammanfoga.

Så, i det här fallet är eb41d76 incheckningen i vår undermodul som vi hade och c771610 är incheckningen som uppströms hade. Om vi går in i undermodulkatalogen ska den redan stå på eb41d76 eftersom sammanslagningen inte rörde den. Om den av någon anledning inte gör det kan du helt enkelt skapa och växla till en gren som pekar på den.

Det viktiga är SHA‑1‑värdet för incheckningen på den andra sidan. Det är det du måste sammanfoga in och lösa. Du kan antingen försöka sammanfoga med SHA‑1:an direkt, eller skapa en gren för den och sedan försöka sammanfoga den. Vi föreslår det senare, om inte annat för att få ett trevligare sammanslagningsmeddelande.

Så vi går in i undermodulkatalogen, skapar en gren som heter “try-merge” baserad på den andra SHA‑1:an från git diff, och sammanfogar manuellt.

Vi fick en riktig sammanslagningskonflikt här, så om vi löser den och checkar in den kan vi helt enkelt uppdatera huvudprojektet med resultatet.

Det kan vara lite förvirrande, men det är egentligen inte så svårt.

Intressant nog finns det ett annat fall som Git hanterar. Om det finns en sammanslagningsincheckning i undermodulkatalogen som innehåller båda incheckningarna i sin historik kommer Git att föreslå den som en möjlig lösning. Den ser att någon vid något tillfälle i undermodulsprojektet sammanfogade grenar som innehåller de två incheckningarna, så kanske vill du ha den.

Det är därför felmeddelandet från tidigare var “merge following commits not found”, eftersom den inte kunde göra detta. Det är förvirrande eftersom vem skulle förvänta sig att den ens försöker göra detta?

Om den hittar en enda godtagbar sammanslagningsincheckning ser du något som detta:

Det föreslagna kommandot som Git ger uppdaterar indexet som om du hade kört git add (vilket rensar konflikten) och checkar in sedan. Du borde dock förmodligen inte göra det. Du kan lika gärna gå in i undermodulkatalogen, se vad skillnaden är, snabbspola till den incheckningen, testa det ordentligt och sedan checka in.

Detta åstadkommer samma sak, men på det här sättet kan du åtminstone verifiera att det fungerar och att du har koden i undermodulkatalogen när du är klar.

Det finns ett foreach‑kommando för undermoduler som kör ett godtyckligt kommando i varje undermodul. Det kan vara riktigt användbart om du har flera undermoduler i samma projekt.

Till exempel, säg att vi vill starta en ny funktion eller åtgärda ett programfel och att vi har arbete på gång i flera undermoduler. Vi kan enkelt lägga undan allt arbete i alla våra undermoduler.

Sedan kan vi skapa en ny gren och byta till den i alla våra undermoduler.

Du fattar. En riktigt användbar sak du kan göra är att ta fram en snygg, sammanfogad diff av det som har ändrats i ditt huvudprojekt och alla underprojekt också.

Här kan vi se att vi definierar en funktion i en undermodul och anropar den i huvudprojektet. Det här är förstås ett förenklat exempel, men förhoppningsvis ger det en bild av hur det kan vara användbart.

Du kanske vill sätta upp alias för några av dessa kommandon eftersom de kan vara ganska långa och du kan inte ställa in konfigurationsalternativ för de flesta av dem för att göra dem till standard. Vi tog upp hur man sätter upp Git‑alias i Git-alias, men här är ett exempel på vad du kan vilja ställa in om du planerar att arbeta mycket med undermoduler i Git.

På så sätt kan du helt enkelt köra git supdate när du vill uppdatera dina undermoduler, eller git spush för att skicka med kontroll av undermodulsberoenden.

Till exempel kan det vara knepigt att byta gren med undermoduler i Git‑versioner äldre än Git 2.13. Om du skapar en ny gren, lägger till en undermodul där och sedan byter tillbaka till en gren utan den undermodulen har du fortfarande undermodulkatalogen som en ospårad katalog:

Att ta bort katalogen är inte svårt, men det kan vara lite förvirrande att ha den där. Om du tar bort den och sedan byter tillbaka till grenen som har undermodulen behöver du köra submodule update --init för att fylla den igen.

Återigen, inte särskilt svårt, men det kan vara lite förvirrande.

Nyare Git‑versioner (Git >= 2.13) förenklar allt detta genom att lägga till flaggan --recurse-submodules till git checkout, som ser till att undermodulerna hamnar i rätt läge för grenen vi byter till.

Att använda flaggan --recurse-submodules i git checkout kan också vara användbart när du arbetar på flera grenar i överprojektet, där varje gren har undermodulen pekande mot olika incheckningar. När du byter mellan grenar som registrerar undermodulen vid olika incheckningar kommer undermodulen att visas som “modified” och indikera “new commits” när du kör git status. Det beror på att undermodulens läge som standard inte följer med när du byter gren.

Det kan vara riktigt förvirrande, så det är en bra idé att alltid köra git checkout --recurse-submodules när ditt projekt har undermoduler. För äldre Git‑versioner som saknar flaggan --recurse-submodules kan du efter utcheckning köra git submodule update --init --recursive för att få undermodulerna i rätt läge.

Lyckligtvis kan du tala om för Git (>=2.14) att alltid använda flaggan --recurse-submodules genom att sätta konfigurationsalternativet submodule.recurse: git config submodule.recurse true. Som nämnts ovan gör detta också att Git går ner i undermoduler för varje kommando som har ett --recurse-submodules‑alternativ (utom git clone).

Den andra stora fallgropen som många stöter på gäller att byta från underkataloger till undermoduler. Om du har spårat filer i ditt projekt och vill flytta ut dem till en undermodul måste du vara försiktig, annars blir Git irriterad. Anta att du har filer i en underkatalog i ditt projekt och vill byta den till en undermodul. Om du tar bort underkatalogen och sedan kör submodule add skäller Git på dig:

Du måste avköa katalogen CryptoLibrary först. Sedan kan du lägga till undermodulen:

Anta nu att du gjorde detta i en gren. Om du försöker byta tillbaka till en gren där filerna fortfarande ligger i det faktiska trädet i stället för en undermodul får du detta fel:

Du kan tvinga fram bytet med checkout -f, men var försiktig så att du inte har osparade ändringar där, eftersom de kan skrivas över.

Sedan, när du byter tillbaka, får du av någon anledning en tom CryptoLibrary‑katalog och git submodule update kanske inte heller fixar det. Du kan behöva gå in i undermodulkatalogen och köra git checkout . för att få tillbaka alla filer. Du kan köra detta i ett submodule foreach‑skript för att göra det på flera undermoduler.

Det är viktigt att notera att undermoduler numera håller all sin Git‑data i överprojektets .git‑katalog, så till skillnad från mycket äldre Git‑versioner förlorar du inga incheckningar eller grenar genom att radera en undermodulkatalog.

Med dessa verktyg kan undermoduler vara en ganska enkel och effektiv metod för att utveckla flera relaterade men fortfarande separata projekt samtidigt.