5.11 Git инструменти - Подмодули

Най-простият модел на работа с подмодули е просто да ги ползвате в проекта си без да ги модифицирате и от време на време да проверявате за промени по тях. Да видим малък пример.

Ако искате да проверите за нова работа в даден подмодул, можете да влезете в директорията му и да изпълните git fetch и git merge към upstream клона.

Ако сега се върнете в основния проект и изпълните git diff --submodule, може да видите че подмодула е обновен и да получите списък на къмитите добавени в него. Ако не искате да пишете --submodule при всяко изпълнение на git diff, може да зададете опцията като подразбираща се с конфигурационната настройка diff.submodule, на която трябва да дадете стойност “log”.

Ако къмитнете на този етап, ще заключите подмодула да получава нов код, когато други хора ъпдейтват.

Има и по-лесен начин да направите това, ако не ви се иска ръчно да дърпате и сливате в поддиректориите. Ако изпълните git submodule update --remote, Git ще премине през подмодулите, ще ги изтегли и ще ги обнови вместо вас.

Командата по подразбиране приема, че желаете да обновите съдържанието на master клона в хранилището на подмодула (този, към който сочи HEAD в отдалеченото хранилище). Но можете да промените това поведение, ако желаете. Например, ако искате DbConnector подмодула да следи клона “stable” от хранилището си, можете да зададете това или в .gitmodules файла (така че и всички останали да следят този клон) или само в локалния ви файл .git/config. Нека използваме .gitmodules:

Ако пропуснете частта -f .gitmodules командата ще направи промяната само за вас, но вероятно е по-смислено да следите тази информация с хранилището, така че всички останали да правят същото.

Когато пуснем git status сега, Git ще ни покаже, че имаме “нови къмити” в подмодула.

Ако активирате конфигурационната настройка status.submodulesummary, Git също така ще ви показва кратък списък на промените в подмодулите ви:

Изпълнението на git diff сега ще ни покаже, че сме модифицирали .gitmodules файла ни и че имаме няколко къмита, които сме изтеглили и са готови да бъдат къмитнати в submodule проекта.

Това е добре, защото можем в действителност да видим информацията от къмитите, която ще къмитнем в нашия подмодул. Веднъж къмитната, тази информация е видима и по-късно, когато изпълним git log -p.

По подразбиране Git ще се опитва да обновява всички подмодули при изпълнение на git submodule update --remote. Ако те са повечко, можете да подадете само името на този, който желаете да обновите.

Нека сега се поставим в ролята на вашия сътрудник, който има собствено локално копие на MainProject хранилището. Само изпълнението на git pull за издърпване на вашите промени не е достатъчно:

По подразбиране, git pull рекурсивно изтегля промените по подмодулите, както може да се види от изхода на първата команда отгоре. Обаче, тя не обновява подмодулите. Това е видно от изхода на git status, която показва, че подмодулът е “modified”, и че има “new commits”. В допълнение, скобите показващи новите къмити сочат наляво (<), което значи, че тези нови къмити са записани в MainProject, но не са налични в локалното DbConnector работно копие. За да финализирате обновлението, ще трябва да изпълните git submodule update:

Отбележете, че за да сте напълно сигурни, би трябвало да изпълните git submodule update с флага --init (в случай че MainProject къмитите, които току що сте издърпали, добавят нови подмодули), и с --recursive флага, ако някой от подмодулите съдържат вложени подмодули.

Ако искате да автоматизирате този процес, може да добавите флага --recurse-submodules към git pull (от версия на Git 2.14). Това ще накара Git д аизпълни git submodule update веднага след изтеглянето, което да постави подмодулите в коректен режим. Освен това, ако желаете Git винаги да тегли с --recurse-submodules, може да укажете това с конфигурационната опция submodule.recurse (това ще важи от версия 2.15 и нагоре). Така Git ще използва флага --recurse-submodules за всички команди, които го поддържат (с изключение на clone).

Съществува специална ситуация, която може да възникне при издърпване на промени от подпроект: може upstream хранилището да е променило адреса на подмодула в .gitmodules файла в някой от къмитите, които теглите. Това може да стане, ако например проектът на подмодула е със сменена хостинг платформа. В такъв случай е възможно командите git pull --recurse-submodules, или git submodule update да не успеят, ако главният проект сочи към къмит на подмодул, който не се намира в локално конфигурирания в хранилището submodule remote. За да се избегне тази ситуация е необходима командата git submodule sync:

Ако ползвате подмодули, твърде вероятно е да искате да работите и по техния код едновременно с основния проект. В противен случай може да предпочетете да ползвате по-проста dependency management система като Maven или Rubygems.

Да разгледаме пример с промяна на кода на подмодул и на основния проект, къмитване и публикуване на промените.

Досега, когато изпълнявахме git submodule update командата за да изтеглим промените от хранилищата на подмодулите, Git ще взема новия код и ще обновява файловете в поддиректориите, но ще ги остави в режим известен като “detached HEAD”. Това означава, че нямаме работещ локален клон (като master например) следящ промените. Липсата на такъв клон означава, че дори да къмитнете промени по подмодула, тези промени е твърде вероятно да се загубят при следващото изпълнение на git submodule update. Необходими са малко допълнителни стъпки, ако искате промените в подмодул да бъдат следени.

Две неща трябва да се направят. Трябва да отидете в директорията на всеки подмодул и да стартирате клон, по който да работите. След това трябва да инструктирате Git как да действа, ако сте направили промени и след това git submodule update --remote внесе нови данни от upstream хранилището. Опциите са да можете да ги слеете с локалната ви работа или да се опитате да пребазирате локалната работа върху новите промени.

Първо, да влезем в директория на подмодул и да създадем клон.

Нека опитаме с опцията “merge”. За да я подадем ръчно, добавяме --merge към update повикването. Тук ще видим, че на сървъра е имало промяна в кода на този подмодул и тя се слива.

Ако влезем в DbConnector директорията, ще имаме новите данни слети в локалния stable клон. Сега нека видим какво се случва, ако направим наша собствена промяна в библиотеката и някой друг публикува друга upstream промяна по същото време.

Пускаме обновяването на подмодула при едновременно налични локална и отдалечена промяна, която трябва да внедрим.

Ако забравите --rebase или --merge, Git просто ще обнови подмодула до съдържанието на сървъра и ще върне проекта в режим detached HEAD.

Ако това се случи, не е голям проблем, можете просто да се върнете в директорията и да извлечете клона отново (той все още ще съдържа вашата работа), след което да слеете или пребазирате origin/stable (или който и да е отдалечен клон) ръчно.

Ако не сте къмитнали промените си в подмодула и пуснете обновяване, което би могло да предизвика проблеми, Git ще издърпа промените, но няма да презапише несъхранената работа в поддиректорията.

Също, ако сте направили промени, които водят до конфликт с нещо променено в upstream-а, Git ще ви уведоми за това.

Можете да влезете в поддиректорията и да оправите конфликта по нормалния начин.

Сега имаме промени в директорията на подмодула. Някои от тях идват от upstream-а след обновяване а други са направени ръчно локално и не са достъпни за никой друг, защото все още не сме ги публикували.

Ако къмитваме в главния проект и го публикуваме без да включим промените в подмодула, то другите хора, които ползват кода ни ще бъдат в затруднение, защото няма да имат начин да се се сдобият с тези промени, а коректната работа на основния проект може да зависи от тях. Тези промени ще са само в локалното ви копие.

За да сте сигурни, че това няма да се случва, можете да укажете на Git да проверява дали всички подмодули са публикувани успешно преди да публикува основния проект. Командата git push приема аргумента --recurse-submodules, който може да се зададе със стойности “check” или “on-demand”. Стойността “check” ще направи така, че публикуването да бъде отказано, ако произволна къмитната промяна в подмодул не е била публикувана успешно.

Както се вижда, получавате и напътствия как бихте могли да продължите. Най-простата възможност е да преминете през директориите на всички подмодули и ръчно да публикувате съдържанието им, след което да се върнете и да пробвате да публикувате главния проект. Ако искате това поведение с проверка да е валидно за всички публикувания, можете да изпълните git config push.recurseSubmodules check

Другата опция е да използвате стойността “on-demand”, което ще опита да свърши работата за вас.

Както се вижда тук, Git е отишъл в DbConnector модула и е публикувал него преди да опита Push за главния проект. Ако по някаква причина този подмодул не успее да се публикува, главния проект също няма да успее. За да направите това поведение подразбиращо се, изпълнете git config push.recurseSubmodules on-demand.

Ако промените референция на подмодул по същото време като някой друг, може да възникнат проблеми. Това е ситуация, при която историите на подмодул са се разделили и са къмитнати в разделящи се клонове в суперпроект.

Ако единият от къмитите е директен предшественик на другия (fast-forward merge), тогава Git просто ще избере последния за сливането, така че това работи добре.

Обаче, Git няма да опита да направи за вас дори и тривиално сливане. Ако къмитите на подмодул се разделят и трябва да се слеят, ще получите нещо такова:

Какво се случва тук? Git е установил, че двата клона пазят точки от историята на подмодула, които са разделени и трябва да се слеят. Това установяваме от съобщението “merge following commits not found”, което само по себе си е объркващо, но ще обясним какво иска да каже след малко.

За да решите проблема, трябва да установите в какъв статус би трябвало да е модула. Странно, но Git тук в действителност не ви помага с информация, не посочва дори SHA-1 хеш стойностите на къмитите от двете страни на историята. За щастие, това е лесно за извличане. Ако пуснете git diff можете да получите SHA-1 стойностите на къмитите в двата клона, които сте се опитали да слеете.

В този случай, eb41d76 е къмитът в нашия подмодул, който ние сме имали и c771610 е upstream къмита. Ако отидем в поддиректорията на модула, той вече трябва да е на eb41d76, защото сливането не го е променило. Ако по някаква причина не е, може просто да създадете нов клон сочещ към него.

Важната част е SHA-1 стойността на къмита от другата страна. Това е, което трябва да слеете и коригирате. Можете или да опитате сливане с SHA-1 стойността директно или може да създадете клон за нея и да опитате сливането в него. Бихме препоръчали второто, дори само за да създадете по-добро merge commit съобщение.

И така, ще отидем в поддиректорията, ще създадем клон наречен “try-merge”, базиран на тази втора SHA-1 стойност, изведена от git diff и ще слеем ръчно.

Тук получихме конфликт, така че ако го разрешим и къмитнем, тогава просто можем да обновим главния проект с резултата.

Може да е леко смущаващо, но не е толкова трудно.

Съществува и още един интересен случай, който Git обработва. Ако в директорията на подмодула съществува merge къмит, който съдържа и двата къмита в историята си, Git ще ви го предложи като възможно решение. Той вижда, че на даден етап от този submodule проект, някой вече е слял клоновете съдържащи тези два къмита, така че може да искате този къмит.

Ето защо объркващото съобщение от по-горе гласеше “merge following commits not found”, защото системата не може да направи това. Объркващият текст идва, защото едвали някой би очаквал Git дори да опита да направи това.

Ако вместо това Git намери приемлив сливащ къмит, ще видите нещо от рода:

Това, което ви се предлага е да обновите индекса както ако бяхте изпълнили git add (което изчиства конфликта) и след това да къмитнете. Но вероятно не трябва да правите това. Можете също толкова лесно да влезете в поддиректорията, да видите каква е разликата, да направите fast-forward до този къмит, да го тествате и след това да къмитнете.

Това ви дава същия резултат, но най-малкото по този начин може да проверите, че нещата работят и разполагате с кода в поддиректорията когато сте готови.

Съществува foreach команда, която ви позволява да изпълнявате други команди за всеки подмодул, като в цикъл. Това е полезно, ако имате много подмодули в проекта.

Да кажем, че стартираме работа по нова функционалност или оправяме грешка и същевременно имаме текущо свършена работа в няколко подмодула. Можем лесно да маскираме (stash) работата по всички подмодули наведнъж.

След това, можем да създадем и превключим към нов клон във всички подмодули едновременно.

В общи линии получавате представа. Едно наистина полезно нещо е, че можете да изведете добре изглеждащ унифициран diff на това какво се е променило в главния проект и също във всички подмодули.

Тук се вижда, че дефинираме функция в подмодул и я викаме в главния проект. Очевидно примерът е прост, но да се надяваме че получавате представа как foreach може да бъде полезна опция.

Някои от тези команди може да са доста дълги и неудобни за писане, а и не за всички може да направите подразбиращи се настройки в конфигурацията. Така че, вероятно бихте искали да създадете псевдоними за тях. Ние погледнахме как се правят псевдоними в Git в Псевдоними в Git, но ето пример какво бихте могли да зададете, ако планирате да работите интензивно с подмодули.

По този начин можете просто да изпълните git supdate, когато искате да обновите подмодулите си или git spush за да публикувате с dependancy checking за тях.

Така например, превключването на клонове с подмодули в тях може да е проблематично при версии на Git по-стари от 2.13. Ако създадете клон, добавите подмодул в него и след това превключите обратно към клон без този подмодул, ще получите поддиректорията му като непроследявана директория в проекта:

Изтриването на тази директория е лесно, но е малко смущаващо да трябва да правите това. Ако я премахнете и след това превключите обратно към клона с подмодула, ще трябва да изпълните submodule update --init за да възстановите данните в нея.

Не е твърде сложно, но е някак неприсъщо.

Версиите на Git от 2.13 и нагоре опростяват всичко това добавяйки флага --recurse-submodules към командата git checkout, която се грижи за поставянето на подмодулите в правилния статус за клона, към който превключваме.

Използването на флага --recurse-submodules към git checkout може да е полезно и когато работите по множество клонове в подпроекта, във всеки от които подмодула ви сочи към различни къмити. Наистина, ако превключите между клонове, които пазят подмодула в различни къмити, git status ще рапортува подмодула като “modified” и ще индикира “new commits”. Това е така, защото по подразбиране статуса на подмодула не се обслужва по време на превключване между клоновете.

Това може да е наистина смущаващо, така че добра идея е винаги да използваме git checkout --recurse-submodules, когато проектът съдържа подмодули. За по-стари версии на Git, които не поддържат флага --recurse-submodules, след извличането може да изпълните git submodule update --init --recursive за да поставите подмодулите в правилния режим.

За щастие, може да инструктирате Git (>=2.14) винаги да използва флага --recurse-submodules през конфигурационната опция submodule.recurse: git config submodule.recurse true. Както отбелязахме по-горе, това също така ще накара Git да минава рекурсивно по подмодулите за всяка команда, която поддържа --recurse-submodules (с изключение на git clone).

Друг значим проблем, който много хора срещат, идва при превклюването от поддиректории към подмодули. Ако проследявате файлове в проекта ви и искате да ги преместите в подмодул, трябва да внимавате или ще си навлечете гнева на Git. Допускаме, че имате файлове в директория от проекта и искате да я прехвърлите към подмодул. Ако изтриете поддиректорията и след това изпълните submodule add, Git ще откаже това:

Трябва първо да извадите от индекса директорията CryptoLibrary. След това можете да добавите подмодула:

Сега представете си, че сте направили това в отделен клон. Ако се опитате да превключите обратно към клон (примерно master), в който тези файлове все още са в действителното дърво, а не в подмодул — ще получите грешка:

Можете да форсирате превключването с checkout -f, но внимавайте да нямате незаписани промени там, защото те могат да бъдат презаписани с тази команда.

След това, когато превключите обратно, получавате празна CryptoLibrary директория по някаква причина и git submodule update може да не може да оправи това. Ще трябва да отидете в поддиректорията и да изпълните git checkout . за да си върнете файловете. Бихте могли да стартирате това в submodule foreach скрипт, за да го изпълните за повече подмодули.

Важно е да отбележим, че подмодулите в днешни дни пазят всичките си Git данни в .git директорията на главния проект, така че унищожаването на директория на подмодул няма да изтрие клоновете или къмитите, които сте имали. Това беше възможно само при много остарели версии на Git.

С тези инструменти, подмодулите в Git могат да са ефективен и прост начин за разработка в множество взаимно свързани, но все пак независими проекта едновременно.