7.11 Mga Git na Kasangkapan - Mga Submodule

Ang pinakasimpleng modelo ng paggamit ng mga submodule sa isang proyekto ay kung ikaw ay nag-uubos lamang ng isang subproject at nais na makakuha ng mga pagbabago mula dito sa pana-panahon ngunit hindi akwtal na nagbabago ng anuman sa iyong pagsusuri. Talakayin natin ang isang simpleng halimbawa doon.

Kung gusto mong magsuri para sa bagong trabaho sa isang submodule, maaari kang pumunta sa direktoryo at patakbuhin ang git fetch at git merge ang upstream na branch upang ma-update ang lokal na code.

Kung gusto mo ngayong bumalik sa pangunahing proyekto at patakbuhin ang git diff --submodule, maaari mong makita na ang submodule ay na-update at makakuha ng isang listahan ng mga commit na naidagdag dito. Kung hindi mo gusto na magtipa ng --submodule sa bawat oras na patakbuhin mo ang git diff, maaari mong itakda ito bilang default na format sa pamamagitan ng pagtatakda sa config na halaga ng diff.submodule sa “log”.

Kung nag-commit ka sa puntong ito pagkatapos ay ila-lock mo ang submodule sa pagkakaroon ng bagong code kapag nag-update ang iba pang mga tao.

Mayroong din isang mas madaling paraan upang gawin ito, kung naisin mo na hindi manu-manong kunin at i-merge sa subdirectory. Kung patakbuhin mo ang git submodule update --remote, pupuntahan ng Git ang iyong mga submodule at kunin at i-update para sa iyo.

Ang utos na ito ay ipagpalagay bilang defualt na nais mong i-update ang paglabas sa branch ng master ng repositoryo ng submodule. Kaya mo, gayunpaman, itakda ito sa ibang bagay kung gusto mo. Halimbawa, kung gusto mo na subaybayan ng DbConnector na submodule ang “stable” na branch ng repostiryong iyon, maaari mong itakda ito sa alinman sa iyong file na .gitmodules (upang subaybayan din ng iba), o sa iyong lokal na .git/config na file lamang. Itakda natin ito sa .gitmodules na file:

Kung iiwanan mo ang -f .gitmodules, ito ay gagawa lamang ng pagbabago para sa iyo, ngunit malamang na ito ay mas makatutulong upang masubaybayan ang impormasyong iyon sa repositoryo upang ang iba naman ay makagagawa rin.

Kapag patakbuhin natin ang git status sa puntong ito, ipapakita ng Git sa atin na mayroon tayong “bagong mga commit” sa submodule.

Kung nagtatakda ka ang setting ng pagsasaayos na status.submodulesummary, ipapakita din ng Git sa iyo ang isang maikling buod ng mga pagbabago sa iyong mga submodule:

Sa puntong ito kung patakbuhin mo ang git diff maaari nating parehong makita na binago natin ang ating` .gitmodules` na file at na mayroon ding isang bilang ng mga commit na ating na-pull pababa at handa na i-commit sa ating submodule na proyekto.

Ito ay medyo astig bilang maaari nating aktwal na makita ang log ng mga commit na ating iko-commit sa ating submodule. Sa sandaling na-commit, maaari mong makita ang impormasyong ito pagkatapos ng katotohanan pati na rin kapag nagpatakbo ka ng git log -p.

Bilang default, susubukan ng Git na i-update ang lahat ng iyong mga submodule kapag nagpatakbo ka ng git submodule update --remote kaya kung mayroon kang maraming mga ito, maaari mong gustuhin na ipasa ang pangalan ng submodule lamang na gusto mong subukang i-update.

Malamang na kung gumagamit ka ng mga submodule, ginagawa mo ito dahil gusto mo talagang magtrabaho sa code sa submodule sa parehong oras habang nagtatrabaho ka sa code sa pangunahing proyekto (o sa ilang mga submodule). Kung hindi man ay malamang na ikaw ay gumamit ng isang mas simple na sistema ng pamamahala ng dependensya (tulad ng Maven o Rubygems).

Kaya ngayon ay talakayin natin ang isang halimbawa ng paggawa ng mga pagbabago sa submodule sa parehong oras sa pangunahing proyekto at pag-commit at paglalathala sa mga pagbabago iyon sa parehong oras.

Sa ngayon, kapag pinatakbo natin ang utos na git submodule update upang makuha ang mga pagbabago mula sa mga repositoryo ng submodule, makakakuha ang Git ng mga pagbabago at i-update ang mga file sa subdirectory ngunit iiwan ang sub-repository sa tinatawag na estado na `nakahiwalay na HEAD''. Ito ay nangangahulugan na walang lokal na tinatrabahuang branch (tulad ng ``master'', halimbawa) na nagsusubaybay ng mga pagbabago. Ng walang tinatrabahuang branch na nagsusubaybay ng mga pagbabago, iyon ay nangangahulugan na kahit na ikaw ay mag-commit ng mga pagbabago sa submodule, ang mga pagbabagong iyon ay posibleng mawala sa susunod na patakbuhin mo ang `git submodule update. Kailangan mong gawin ang ilang mga dagdag na hakbang kung nais mong baguhin ang mga submodule na susubaybayan.

Para ma-set up ang iyong submodule na maging mas madaling pasukin at i-hack, kailangan mong gawin ang dalawang bagay. Kailangan mong puntahan ang bawat submodule at suriin ang isang branch na tatrabahuin. Pagkatapos ay kailangan mong sabihan ang Git kung ano ang gagawin kung may ginawa kang mga pagbabago at pagkatapos ay ipu-pull ng git submodule update --remote sa bagong trabaho mula sa upstream. Ang mga pagpipilian ay maaari kang mag-merge ng mg ito sa iyong lokal na trabaho, o subukang i-rebase ang iyong lokal na trabaho sa itaas ng mga bagong pagbabago.

Una sa lahat, puntahan natin ang ating submodule na direktoryo at suriin ang isang branch.

Subukan natin ito sa opsyon na “merge”. Upang itakda ito nang mano-mano, maaari lamang nating idagdag ang pagpipilian na --merge sa ating update na pagtawag. Dito, makikita natin na may isang pagbabago sa server para sa submodule na ito at ito ay nai-merge.

Kung pupuntahan natin ang DbConnector na direktoryo, mayroon na tayong mga bagong pagbabago na na-merge sa lokal stable na branch. Ngayon, tingnan natin kung ano ang nangyayari kapag gagawa tayo ng sariling lokal na pagbabago sa library at may ibang tao na mag-push ng iba pang pagbabago na upstream sa parehong oras.

Ngayon kung ating ia-update ang ating submodule, makikita natin kung ano ang nangyayari kapag gumawa tayo ng isang lokal na pagbabago at ang upstream din ay may isang pagbabago na kailangan nating isama.

Kung nalimutan mo ang --rebase o --merge, ia-update lamang ng Git ang submodule sa kung anuman ang nasa server at ilagay muli ang iyong proyekto sa isang tinanggal na HEAD na estado.

Kung mangyayari ito, huwag mag-alala, maaari kang bumalik sa direktoryo at suriing muli ang iyong branch (kung saan ay naglalaman pa rin ng iyong trabaho) at i-merge o i-rebase nang mano-mano ang origin/stable (o kung anuman ang gustong mong remote na branch).

Kung hindi ka pa naka-commit ng iyong mga pagbabago sa iyong submodule at nagpatakbo ka ng isang update ng submodule na magiging sanhi ng mga isyu, kukunin ng Git ang mgs pagbabago ngunit hindi nito sasapawan ang mga hindi na-save na trabaho sa iyong submodule na direktoryo.

Kung gumawa ka ng mga pagbabago na sumasalungat sa ilang nabago na upstream, ipapaalam sa iyo ng Git kapag pinatakbo mo ang update.

Maaari kang magpunta sa submodule na direktoryo at ayusin ang salungatan tulad ng karaniwan mong ginagawa.

Ngayon ay mayroon na tayong iilang mga pagbabago sa ating submodule na direktoryo. Ilan sa mga ito ay dinala mula sa upstream sa pamamagitan ng ating mga update at ang iba ay ginawa sa lokal at hindi pa magagamit ng sinuman dahil hindi pa natin na-push ang mga ito.

Kung tayo ay nag-commit sa pangunahing proyekto at pi-nush ito, nang wala ring pag-push sa mga pagbabago ng submodule, ang ibang tao na nagsusubok na mag-check out ng mga pagbabago ay magkakaroon ng problema dahil wala silang paraan upang makuha ang mga naka-dependeng pagbabago sa submodule. Ang mga pagbabagong iyon ay umiiral lamang sa ating lokal na kopya.

Para makasiguro na hindi na ito mangyayari, maaari mong hilingin sa Git na suriin na ang lahat ng iyong mga submodile ay na-push nang maayos bago mag-push sa pangunahing proyekto. Ang utos git push ay tumatanggap ng argumento na --recurse-submodules na kung saan maaari itakda ang alinman sa “check” o “on-demand”. Ang opsyon na “check” ay simpleng bibigo sa push kung anuman sa mga na-commit na pagbabago ng submodule ay hindi na-push.

Tulad ng iyong nakikita, nagbibigay din ito sa atin ng ilang kapaki-pakinabang na payo tungkol sa kung ano ang maaari nating gawin sa susunod. Ang simpleng pagpipilian ay pumunta sa bawat submodule at mano-manong i-push sa mga remote upang matiyak na magagamit ang mga ito sa labas at pagkatapos ay subukang muli ang push na ito. Kung nais mong suriin ang kilos na mangyayari para sa lahat ng push, maaari mong gawing default ang kilos na ito sa pamamagitan ng paggawa ng git config push.recurseSubmodules check.

Ang isa pang opsyon ay ang paggamit ng “on-demand” na halaga, na susubukan na gawin ito para sa iyo.

Tulad ng makikita mo doon, nagpunta si Git sa module ng DbConnector at nag-push ito bago mag-push sa pangunahing proyekto. Kung ang submodule push ay nabigo para sa ilang kadahilanan, ang pangunahing push ng proyekto ay mabibigo din. Maaari mong gawing default ang kilos na ito sa pamamagitan ng paggawa ng git config push.recurseSubmodules on-demand.

Kung binago mo ang isang reperensya ng submodule sa parehong oras bilang ibang tao, maaari kang makaranas ng ilang mga problema. Iyon ay, kung ang mga kasaysayan ng submodule ay magkaiba at na-commit sa mga magkaibang branch sa isang superproject, maaaring tumagal nang kaunti na maayos ito.

Kung ang isa sa mga commit ay isang direktang ninuno ng iba pan (isang mabilis na pagsasama), pagkatapos ay piliin lamang ng Git ang huli para sa pagsasama, upang ito ay gumana.

Ang Git ay hindi magtatangkang kahit isang maliit na pag-merge para sa iyo, gayunpaman. Kung ang submodule ay gumagawa ng magkaiba at kailangang i-merge, makakakuha ka ng isang bagay na mukhang ganito:

So basically what has happened here is that Git has figured out that the two branches record points in the submodule’s history that are divergent and need to be merged. It explains it as “merge following commits not found”, which is confusing but we’ll explain why that is in a bit.

To solve the problem, you need to figure out what state the submodule should be in. Strangely, Git doesn’t really give you much information to help out here, not even the SHA-1s of the commits of both sides of the history. Fortunately, it’s simple to figure out. If you run git diff you can get the SHA-1s of the commits recorded in both branches you were trying to merge.

So, in this case, eb41d76 is the commit in our submodule that we had and c771610 is the commit that upstream had. If we go into our submodule directory, it should already be on eb41d76 as the merge would not have touched it. If for whatever reason it’s not, you can simply create and checkout a branch pointing to it.

What is important is the SHA-1 of the commit from the other side. This is what you’ll have to merge in and resolve. You can either just try the merge with the SHA-1 directly, or you can create a branch for it and then try to merge that in. We would suggest the latter, even if only to make a nicer merge commit message.

So, we will go into our submodule directory, create a branch based on that second SHA-1 from git diff and manually merge.

We got an actual merge conflict here, so if we resolve that and commit it, then we can simply update the main project with the result.

It can be a bit confusing, but it’s really not very hard.

Interestingly, there is another case that Git handles. If a merge commit exists in the submodule directory that contains both commits in its history, Git will suggest it to you as a possible solution. It sees that at some point in the submodule project, someone merged branches containing these two commits, so maybe you’ll want that one.

This is why the error message from before was “merge following commits not found”, because it could not do this. It’s confusing because who would expect it to try to do this?

If it does find a single acceptable merge commit, you’ll see something like this:

What it’s suggesting that you do is to update the index like you had run git add, which clears the conflict, then commit. You probably shouldn’t do this though. You can just as easily go into the submodule directory, see what the difference is, fast-forward to this commit, test it properly, and then commit it.

This accomplishes the same thing, but at least this way you can verify that it works and you have the code in your submodule directory when you’re done.

There is a foreach submodule command to run some arbitrary command in each submodule. This can be really helpful if you have a number of submodules in the same project.

For example, let’s say we want to start a new feature or do a bugfix and we have work going on in several submodules. We can easily stash all the work in all our submodules.

Then we can create a new branch and switch to it in all our submodules.

You get the idea. One really useful thing you can do is produce a nice unified diff of what is changed in your main project and all your subprojects as well.

Here we can see that we’re defining a function in a submodule and calling it in the main project. This is obviously a simplified example, but hopefully it gives you an idea of how this may be useful.

You may want to set up some aliases for some of these commands as they can be quite long and you can’t set configuration options for most of them to make them defaults. We covered setting up Git aliases in Mga Alyas sa Git, but here is an example of what you may want to set up if you plan on working with submodules in Git a lot.

This way you can simply run git supdate when you want to update your submodules, or git spush to push with submodule dependency checking.