5.2 Porazdeljeni Git - Prispevek k projektu

Preden začnemo gledati določene primere uporabe, je tu hitro obvestilo o sporočilih potrditev. Imeti dobre smernice za ustvarjanje potrditev in se jih držati, naredi delo z Gitom in sodelovanjem z ostalimi veliko enostavnejše. Projekt Git ponuja dokument, ki začrta število dobrih nasvetov za ustvarjanje potrditev, iz katerih se pošljejo popravki — to lahko preberete v izvorni kodi Git v datoteki Documentation/SubmittingPatches.

Kot prvo, ne želite poslati kakršnih koli napak praznih znakov. Git ponuja enostaven način, da to preverite — preden potrdite, poženite git diff --check, ki identificira vse možne napake praznih znakov in vam jih izpiše.

Če poženete ta ukaz preden potrdite, lahko poveste, ali ste tik pred tem, da potrdite tudi težave s praznimi znaki, ki lahko nagajajo ostalim razvijalcem.

Naslednje poskusite narediti vsako potrditev kot logičen ločen skupek sprememb. Če lahko, poskusite narediti svoje spremembe prebavljive — ne kodirajte cel vikend na petih različnih težavah in nato pošljite vse kot eno masovno potrditev v ponedeljek. Tudi če ne naredite potrditve med koncem tedna, uporabite področje priprave v ponedeljek, da se loči vaše delo v vsaj eno potrditev na težavo z uporabnim sporočilom na potrditev. Če nekatere spremembe spremenijo isto datoteko, poskusite uporabiti git add --patch za delno pripravo datoteke (podrobno pokrito v razdelku Interaktivno pripravljanje). Posnetek projekta pri vrhu veje je identičen, če naredite eno ali pa pet potrditev, dokler so vse spremembe dodane na neki točki, torej poskusite narediti stvari enostavne za svoje kolege razvijalce, ko bodo morali pregledati vaše spremembe.

Ta pristop naredi enostavnejše tudi vlečenje ali povrnitev ene izmed skupka sprememb, če to kasneje potrebujete. Razdelek Prepisovanje zgodovine opisuje število uporabnih trikov Git za prepisovanje zgodovine in interaktivno dajanje datotek v področje priprave — uporabite ta orodja, da vam pomagajo izdelati čisto in razumljivo zgodovino, preden pošljete delo nekomu drugemu.

Zadnja stvar za pomnjenje je sporočilo potrditve. Navaditi se ustvarjati kakovostna sporočila potrditev naredi uporabo in sodelovanje z Gitom veliko enostavnejše. Kot splošno pravilo bi se vaša sporočila morala začeti z eno vrstico, ki ni večja od 50 znakov in jedrnato opisuje skupek sprememb ter nato ji sledi prazna vrstica, ki ji sledi podrobnejša razlaga. Projekt Git zahteva, da bolj podrobna razlaga vključuje vašo motivacijo za spremembe in kontrast njene implementacije s prejšnjim obnašanjem — to je tudi dobra smernica za sledenje. Napišite svoja sporočila potrditev v velelniku: »Popravi hrošč« in ne »Popravljen hrošč« ali »To popravi hrošč«. Tu lahko sledite tej predlogi, ki smo jo malenkost prilagodili po tej, ki jo je prvotno napisal Tim Pope:

Če vsa vaša sporočila potrditev sledijo temu modelu, so stvari veliko enostavnejše za vas in razvijalce, s katerimi delate. Projekt Git ima dobro oblikovana sporočila potrditev — poskusite tam pognati git log --no-merges, da vidite, kakšna je lepo oblikovana zgodovina potrditev projekta.

Najenostavnejša nastavitev, na katero boste verjetno naleteli, je zasebni projekt z enim ali dvema razvijalcema. »Zasebni« v tem kontekstu pomeni zaprto kodo — ni dostopna za zunanji svet. Vi in ostali razvijalci imate vsi dostop potiskanja v repozitorij.

V tem okolju lahko sledite poteku dela, ki je podoben, kakor ste morda delali, ko ste uporabljali Subversion ali drug centraliziran sistem. Še vedno dobite prednosti stvari, kot so potrjevanje brez povezave in prostrano enostavnejše razvejanje in združevanje, vendar potek dela je lahko zelo podoben; glavna razlika je, da se združevanje zgodi na strani odjemalca namesto na strežniku v času potrditve. Poglejmo, kako je lahko videti, ko dva razvijalca začneta delati skupaj z deljenim repozitorijem. Prvi razvijalec, John, klonira repozitorij, naredi spremembe in jih potrdi lokalno. Sporočila protokola so bila v teh primerih zamenjana s …​, da se nekako skrajšajo.

Druga razvijalka, Jessica, naredi isto stvar — klonira repozitorij in potrdi spremembo:

Sedaj Jessica potisne njeno delo na strežnik:

Zadnja vrstica izhoda zgoraj prikazuje uporabno sporočilo o vrnitvi iz operacije potiska. Osnovni format je <oldref>..<newref> fromref → toref, kjer oldref pomeni staro referenco, newref pomeni novo referenco, fromref je ime lokalne reference, ki jo potiskamo, in toref je ime oddaljene reference, ki jo posodabljamo. Podoben izhod boste videli spodaj v razpravah, zato bo osnovna ideja o pomenu pomagala pri razumevanju različnih stanj repozitorijev. Več podrobnosti najdete v dokumentaciji za git-push.

Če nadaljujemo s tem primerom, kmalu zatem John naredi nekaj sprememb, jih potrdi v svojem lokalnem repozitoriju in jih poskuša potisniti na isti strežnik:

V tem primeru Johnov potisk ni uspešen, ker je vmes potisnila Jessica njene spremembe. To je posebej pomembno razumeti, če ste vajeni Subversiona, ker boste opazili, da dva razvijalca nista uredila iste datoteke. Čeprav Subversion naredi to združevanje avtomatično na strežniku, če se urejajo različne datoteke, morate z Gitom najprej združiti potrditve lokalno. Z drugimi besedami, John mora najprej prenesti zgornje spremembe Jessice in jih združiti v svoj lokalni repozitorij, preden bo smel potisniti.

Kot prvi korak John prenese delo Jessice (to samo prenese zgornje delo Jessice in ga še ne združi v Johnovo delo):

Na tej točki je Johnov lokalni repozitorij videti nekako takole:

Sedaj lahko John združi Jessicino delo, ki ga je prenesel v svoje lokalno delo:

Dokler gre to lokalno združevanje gladko, bo Johnova posodobljena zgodovina sedaj videti nekako takole:

Sedaj lahko John testira to novo kodo, da zagotovi, da nobeno delo Jessice ne vpliva na nobeno njegovo in dokler poteka vse ustrezno, lahko potisne novo združeno delo na strežnik:

Na koncu je Johnova zgodovina potrditev videti nekako takole:

Vmes je Jessica ustvarila novo tematsko vejo imenovano issue54 in na tej veji naredila tri potrditve. Ni pa še prenesla Johnovih sprememb, zato je njena zgodovina potrditev videti nekako takole:

Nenadoma Jessica izve, da je John potisnil nekaj novega dela na strežnik, in želi ga pogledati, torej lahko prenese vso novo vsebino iz strežnika, ki je še nima:

To povleče delo, ki ga je vmes John potisnil. Zgodovina Jessice je sedaj videti takole:

Jessica misli, da je njena tematska veja pripravljena, vendar želi vedeti, kateri del prenesenega Johnovega dela mora združiti v njeno delo, da lahko potisne. Požene git log, da ugotovi:

Sintaksa issue54..origin/master je dnevniški filter, ki vpraša Git, da prikaže samo seznam potrditev, ki so na slednji veji (v tem primeru origin/master) in ki niso na prvi veji (v tem primeru issue54). Skozi to sintakso bomo šli podrobneje v Obsegi potrditev.

Iz zgornjega izpisa lahko vidimo, da je ena potrditev, ki jo je naredil John, in je Jessica ni združila v njeno lokalno delo. Če ona združi origin/master, je to ena potrditev, ki bo spremenila njeno lokalno delo.

Sedaj lahko Jessica združi njeno tematsko delo v njeno vejo master, združi, Johnovo delo (origin/master) v njeno vejo master in nato potisne nazaj na strežnik.

Najprej, (ko je potrdila vso delo na svoji tematski veji issue54), preklopi nazaj na njeno vejo master v pripravi, da integrira vso to delo:

Jessica lahko najprej združi origin/master ali pa issue54 — obe sta iz povratnega toka, torej vrstni red ni pomemben. Zadnji posnetek bi moral biti identičen ne glede na vrstni red, ki ga izbere, samo zgodovina bo nekoliko drugačna. Najprej, izbere združiti vejo issue54:

Ne pride do nobenih problemov; kot lahko vidite, je šlo za enostaven fast-forward. Sedaj Jessica zaključi proces lokalnega združevanja in združi prej preneseno delo Johna, ki čaka v veji origin/master:

Vse se gladko združi in zgodovina Jessice je sedaj videti takole:

Sedaj je origin/master dosegljiv iz Jessicine veje master, da lahko uspešno potisne (ob predpostavki, da John vmes ni ponovno potisnil še več sprememb):

Vsak razvijalec je naredil nekaj potrditev in uspešno združil delo drug drugega.

To je eden najenostavnejših potekov dela. Nekaj časa delate, (v splošnem na tematski veji), in združite to delo v vašo vejo master, ko je pripravljeno za integracijo. Ko želite deliti to delo, prenesete in združite vašo vejo master iz origin/master, če se je kaj spremenilo, in na koncu potisnite na vejo master na strežniku. Splošno zaporedje je nekaj takega:

V tem naslednjem scenariju, boste pogledali vloge sodelavcev v večji zasebni skupini. Naučili se boste, kako delati v okolju, kjer sodelujejo manjše skupine na lastnostih, in nato so ti prispevki na osnovi ekip integrirani s strani druge stranke.

Recimo, da John in Jessica delata skupaj na eni lastnosti (recimo featureA), medtem ko Jessica in tretja razvijalka Josie delata na drugi (recimo featureB). V tem primeru podjetje uporablja tip poteka dela upravitelja integracije, kjer je delo posameznih skupin integrirano samo od določenih inženirjev in veja master glavnega repozitorija je lahko posodobljena samo s strani teh inženirjev. V tem scenariju je vse delo narejeno na vejah na osnovi ekip in kasneje povlečene skupaj s strani povezovalcev.

Sledimo poteku dela Jessice, kakor dela na dveh njenih lastnostih, vzporedno sodeluje z dvema različnima razvijalcema v tem okolju. Predpostavimo, da že ima svoj repozitorij kloniran in se odloči delati najprej na lastnosti featureA. Ustvari novo vejo za lastnost in naredi nekaj dela na njej:

Na tej točki morate deliti nekaj dela z Johnom, torej potisne njene potrditve veje featureA na strežnik. Jessica nima dostopa potiskanja na vejo master — to imajo samo povezovalci — torej mora potisniti na drugo vejo, da lahko sodeluje z Johnom:

Jessica sporoči Johnu po e-pošti, da je potisnila nekaj dela v vejo imenovano featureA, in on lahko to sedaj pogleda. Medtem ko čaka na povratne informacije od Johna, se Jessica odloči začeti delati na lastnosti featureB z Josie. Da začne, ustvari novo vejo lastnosti, ki je osnovana na strežniški veji master:

Sedaj, Jessica naredi nekaj potrditev na veji featureB:

Jessicin repozitorij je videti sedaj takole:

Pripravljena je potisniti njeno delo, vendar dobi e-pošto od Josie, da je veja featureB z nekaj začetnega dela na njej že potisnjena na strežnik kot featureBee. Jessica mora najprej združiti te spremembe v njeno lastno, preden lahko potisne svoje delo na strežnik. Jessica najprej prenese spremembe Josie z git fetch:

Ob predpostavki, da je Jessica še vedno na svoji izvlečeni veji featureB, lahko sedaj združi delo Josie v to vejo z git merge:

V tem trenutku Jessica želi vse združeno delo featureB potisniti nazaj na strežnik, vendar noče preprosto potisniti svoje veje featureB. Ker je Josie že začela z zgornjo vejo featureBee, želi Jessica potisniti na to vejo, kar stori s:

To se imenuje refspec. Glejte razdelek Refspec za bolj podrobno diskusijo refspec Gita in različnih stvari, ki jih lahko naredite z njimi. Bodite pozorni tudi na zastavico -u; to je okrajšava za --set-upstream, ki nastavi veje za enostavnejše kasnejše potiskanje in vlečenje.

Nenadoma Jessica prejme e-pošto od Johna, ki ji sporoči, da je potisnil nekaj sprememb na vejo featureA, na kateri sodelujeta, in jo prosi, naj si jih ogleda. Jessica ponovno zažene preprost ukaz git fetch, da prenese vse nove vsebine s strežnika, vključno (seveda) z Johnovim najnovejšim delom:

Jessica lahko prikaže dnevnik Johnovega novega dela s primerjavo vsebine na novo prenesene veje featureA s svojo lokalno kopijo iste veje:

Če je Jessici všeč, kar vidi, lahko združi novo delo Johna v njeno lokalno vejo featureA:

Nazadnje bi Jessica lahko želela narediti nekaj manjših sprememb na vsem tem združenem delu, zato je prosta, da naredi te spremembe, jih potrdi v svoji lokalni veji featureA in potisne končni rezultat nazaj na strežnik:

Zgodovina potrditev Jessice je sedaj videti nekako takole:

V nekem trenutku Jessica, Josie in John obvestijo povezovalce, da sta veji featureA in featureBee na strežniku pripravljeni za integracijo v glavno vejo. Ko povezovalci združijo ti veji v glavno vejo, bo prenos prinesel novo potrditev združitve, zaradi česar bo zgodovina videti takole:

Zaradi te zmožnosti mnoge skupine preklopijo na Git, da imajo več ekip, ki delajo vzporedno in združujejo na različnih vrsticah dela kasneje v procesu. Zmožnost manjših podskupin ekipe, da sodelujejo preko oddaljenih vej brez potrebe po vključevanju ali oviri celotne ekipe, je velika prednost Gita. Zaporedje poteka dela, ki ste ga tu videli, je nekaj takega:

Prispevki k javnim projektom so nekoliko drugačni. Ker nimate dovoljenja neposredno posodobiti veje na projektu, morate nekako dati delo vzdrževalcem na drug način. Prvi primer opisuje prispevke preko razvejanja na gostiteljih Git, ki podpirajo enostavno razvejanje. Mnoge strani gostiteljev to podpirajo (vključno z GitHub, BitBucket, Google Code, repo.or.cz in ostalimi) in mnogi vzdrževalci projektov pričakujejo ta stil prispevkov. Naslednji razdelek se ukvarja s projekti, ki imajo raje sprejeti prispevke popravkov preko e-pošte.

Najprej boste verjetno želeli klonirati glavni repozitorij, ustvariti tematsko vejo za programski popravek ali serijo popravkov, ki jih planirate prispevati in narediti delo tam. Zaporedje je videti v osnovi takole:

Ko je delo vaše veje končano in ste pripravljeni prispevati nazaj vzdrževalcem, pojdite na prvotno stran projekta in kliknite na gumb »Fork«, kar bo ustvarilo vašo lastno zapisljivo razvejitev projekta. Nato morate dodati ta novi URL repozitorija kot novo daljavo svojega lokalnega repozitorija; v tem primeru ga imenujmo myfork:

Nato morate potisniti svoje novo delo v ta repozitorij. Najenostavnejše je potisniti tematsko vejo, na kateri delate, na vaš razvejan repozitorij namesto združevanja v vašo vejo master in potiskanja tega navzgor. Razlog je, da če delo ni sprejeto, ali so izbrane samo najboljše spremembe (angl. cherry picking), vam ni treba previti nazaj vaše veje master (operacija Gita cherry-pick je pokrita bolj podrobno v Poteki dela ponovnega baziranja in izbire najboljšega). Če vzdrževalci združijo, ponovno bazirajo ali izberejo samo najboljše spremembe vašega dela, ga boste tako ali tako eventualno povlekli nazaj iz njihovega repozitorija:

V kateremkoli primeru lahko potisnete svoje delo na naslednji način:

Ko je bilo vaše delo potisnjeno na vašo razvejitev, morate obvestiti vzdrževalce prvotnega projekta, da imate delo, ki ga želite, da ga združijo. To je pogostokrat imenovano zahtevek potega in tak zahtevek običajno generirate preko spletne strani — GitHub ima svoj lastni mehanizem zahtevkov potega, ki jih bomo obravnavali v GitHub — ali pa poženete ukaz git request-pull in pošljete vzdrževalcu projekta dani izpis ročno po e-pošti.

Ukaz git request-pull vzame osnovno vejo, v katero želite povleči svojo tematsko vejo, in URL repozitorija Git, iz katerega želite, da ga povlečejo, ter izpiše povzetek vseh sprememb, za katere želite, da se povlečejo. Na primer, če Jessica želi poslati Johnu zahtevek potega in je končala dve potrditvi na tematski veji, ki jo je ravnokar potisnila, lahko požene tole:

Ta izpis se lahko pošlje vzdrževalcu — pove jim, od kod je delo razvejano, povzame potrditve in pove, od kod povleči to delo.

Na projektu, za katerega niste vzdrževalec, je v splošnem enostavnejše imeti vejo, kot je master, ki vedno sledi origin/master, in narediti vaše delo v tematskih vejah, ki jih lahko enostavno zavržete, če so zavrnjene. Delovne teme, izolirane v tematske veje, so vam tudi enostavnejše, da ponovno bazirate vaše delo, če se je konica glavnega repozitorija vmes premaknila in vaših potrditev ni več mogoče gladko uporabiti. Na primer, če želite poslati drugo temo dela projekta, ne nadaljujte delo na tematski veji, ki ste jo ravnokar potisnili, začnite raje znova iz veje master glavnega repozitorija:

Sedaj je vsaka od vaših tem vsebovana znotraj silosa — podobno kot čakalna vrsta popravka — ki jo lahko prepišete in spremenite, brez da se teme med seboj vmešavajo ali so soodvisne druga od druge:

Recimo, da je vzdrževalec projekta povlekel veliko ostalih popravkov in poskusil vašo prvo vejo, vendar se ne združuje več gladko. V tem primeru lahko to vejo poskusite ponovno bazirati na vrh origin/master, rešite konflikte za vzdrževalca in nato ponovno pošljete svoje spremembe:

To prepiše vašo zgodovino, da je sedaj videti kot na sliki Zgodovina potrditev po delu featureA.

Ker ste vejo ponovno bazirali, morate določiti -f za vaš ukaz potiskanja, da lahko zamenjate vejo featureA na strežniku s potrditvijo, ki ni njen potomec. Alternativa bi bila potisniti to novo delo na drugo vejo na strežniku (mogoče imenovano featureAv2).

Poglejmo en bolj verjeten scenarij: vzdrževalec je pogledal delo v vaši drugi veji in mu je zasnova všeč, vendar bi rad, da spremenite podrobnost implementacije. To priložnost boste tudi vzeli, da premaknete delo, da bo osnovano na trenutni veji projekta master. Začnete novo vejo, ki je osnovana na trenutni veji origin/master, tam stisnite spremembe featureB, rešite kakršnekoli konflikte, naredite implementacijo sprememb in nato to potisnite kot novo vejo:

Možnost --squash vzame vso delo na združeni veji in jih stisne v en skupek sprememb, ki ustvari stanje repozitorija, kakor da bi se zgodilo resnično združevanje, ne da dejansko naredi potrditev združitve. To pomeni, da bo vaša prihodnja potrditev imela samo eno nadrejeno in vam omogoča uvedbo vseh sprememb iz druge veje ter nato naredite več sprememb pred snemanjem nove potrditve. Uporabna je lahko tudi možnost --no-commit, ki zakasni potrditev združitve v primeru privzetega procesa združevanja.

Sedaj lahko pošljete vzdrževalcu sporočilo, da ste naredili zahtevane spremembe in da te spremembe lahko najdejo v vaši veji featureBv2.

Mnogi projekti imajo ustaljene postopke za sprejemanje popravkov — preveriti boste morali določena pravila za vsak projekt, ker se razlikujejo. Odkar je na voljo nekaj starejših, večjih projektov, ki sprejemajo popravke preko razvijalskega e-poštnega seznama, bomo šli sedaj skozi primer tega.

Potek dela je podoben prejšnjemu primeru uporabe — ustvarite tematske veje za vsake serije popravka, na katerih delate. Razlika je, kako jih pošljete projektu. Namesto razvejanja projekta in potiskanja v svojo lastno zapisljivo različico generirate e-poštno različico za vsako od serij potrditev in jih pošljete po e-pošti razvijalskemu e-poštnemu seznamu:

Sedaj imate dve potrditvi, ki ju želite poslati na e-poštni seznam. Uporabili boste git format-patch, da generirate mbox oblikovane datoteke, ki jih lahko pošljete preko e-pošte na seznam — vsako potrditev pretvori v sporočilo e-pošte s prvo vrstico sporočila potrditve kot zadevo in preostanek sporočila ter programski popravek, ki ga potrditev predstavlja kot telo. Dobra stvar pri tem je, da uporaba popravka generiranega iz e-pošte s format-patch ustrezno ohrani vse informacije potrditve.

Ukaz format-patch izpiše imena datotek popravka, ki ga ustvari. Preklop -M pove Gitu, da išče preimenovanja. Datoteke so na koncu videti takole:

Lahko tudi uredite te datoteke popravka, da dodate več informacij za seznam e-pošte, za katere ne želite, da se prikažejo v sporočilu potrditve. Če dodate besedilo med vrstico --- in začetek popravka (vrstica diff --git), potem ga razvijalci lahko preberejo, vendar proces popravka vsebino izključuje.

Da to pošljete po e-pošti na e-poštni seznam, lahko prilepite datoteko v vaš e-poštni program, ali pa pošljete preko programa ukazne vrstice. Lepljenje teksta pogostokrat povzroča težave oblikovanja, posebej s »pametnejšimi« odjemalci, ki ne ohranjajo ustrezno novih vrstic in ostalih praznih znakov. Na srečo, Git ponuja orodje, ki vam pomaga poslati ustrezno oblikovane popravke preko IMAP, kar je za vas lahko enostavnejše. Prikazali bomo, kako poslati programski popravek preko Gmaila, kar je e-poštni agent, ki ga najbolje poznamo; preberete lahko podrobna navodila za število poštnih programov na koncu zgoraj omenjene datoteke Documentation/SubmittingPatches v izvorni kodi Git.

Najprej morate nastaviti razdelek imap v vaši datoteki ~/.gitconfig. Nastavite lahko vsako vrednost ločeno s serijo ukazov git config ali pa jih dodate ročno, vendar na koncu bi vaša nastavitvena datoteka morala biti videti nekako takole:

Če vaš strežnik IMAP ne uporablja SSL, zadnji dve vrstici verjetno nista potrebni in vrednost gostitelja bo imap:// namesto imaps://. Ko je to nastavljeno, lahko uporabite git imap-send, da dodate serijo popravkov v mapo Drafts določenega strežnika IMAP:

V tem trenutku bi morali imeti dostop do vaše mape osnutkov (angl. Drafts), lahko spremenite polje »To« na seznam e-pošte, na katerega pošiljate programski popravek, opcijsko »CC« za vzdrževalca ali osebo, odgovorno za ta razdelek, in lahko ga pošljete.

Programski popravek lahko pošljete tudi preko strežnika SMTP. Kot prej, lahko nastavite vsako vrednost ločeno s serijo ukazov git config, ali pa jih dodate ročno v razdelek sendemail vaše datoteke ~/.gitconfig:

Ko je to narejeno, lahko uporabite git send-email, da pošljete svoje popravke:

Nato Git izpljune kopico informacij dnevnika, kar je videti nekako takole za vsak programski popravek, ki ga pošiljate:

V tem razdelku smo obravnavali več potekov dela in razpravljali o razlikah med delom v majhni ekipi na zaprtem projektu in prispevku k velikemu javnemu projektu. Sedaj veste, kako pred potrditvijo preveriti napake praznih znakov in napisati znate odlično sporočilo potrditve. Naučili ste se, kako oblikovati popravke in kako jih pošljete po e-pošti na seznam razvijalcev. Razpravljali smo tudi o združevanju pri različnih potekih dela. Zdaj ste dobro pripravljeni za sodelovanje na katerem koli projektu.

V nadaljevanju boste videli, kako deluje druga plat medalje: vzdrževanje projekta Git. Naučili se boste, kako biti dobronamerni diktator ali integracijski upravitelj.