5.2 Distribuovaný Git - Přispívání do projektu

Než se podíváme na konkrétní případy, uveďme rychlou poznámku o zprávách k revizím. Pokud stanovíte dobrá pravidla pro vytváření revizí (commit) a pokud se jich budete držet, bude práce s Gitem a spolupráce s ostatními mnohem jednodušší. Samotný projekt Git obsahuje dokument, v němž je navržena celá řada dobrých tipů pro vytváření revizí, z kterých se vytvářejí záplaty. Najdete ho ve zdrojovém kódu systému Git, v souboru Documentation/SubmittingPatches.

Především nechcete odesílat chybně použité prázdné znaky (whitespace). Git nabízí snadný způsob, jak tyto chyby zkontrolovat. Před zapsáním revize spusťte git diff --check, který zkontroluje prázdné znaky a zobrazí vám je.

Spustíte-li tento příkaz před zapsáním revize, můžete zjistit, zda se budou zapisovat i problematické prázdné znaky, které by mohly ostatní vývojáře obtěžovat.

Dále se snažte zapisovat každou revizi (commit) jako logicky oddělený soubor změn. Pokud je to možné, snažte se, aby byly vaše změny stravitelné. Není právě ideální pracovat celý víkend na pěti různých problémech a v pondělí je všechny najednou odeslat formou jedné velké revize. Když už během víkendu nebudete zapisovat revize, využijte v pondělí oblasti připravených změn pro rozdělení práce alespoň do stejného počtu revizí, kolik je řešených problémů, a přidejte k nim vysvětlující zprávy. Pokud některé změny upravují stejný soubor, zkuste použít příkaz git add --patch a připravit soubory k zapsání po částech (podrobnosti jsou popsány v kapitole Interactive Staging). Snímek projektu na vrcholu větve bude stejný, ať zapíšete jednu revizi, nebo pět (za předpokladu, že vložíte všechny změny). Snažte se proto usnadnit práci svým kolegům, kteří možná někdy budou vaše změny revidovat. Takový přístup současně usnadňuje stahování změn (pull) nebo vracení jedné sady změn do původního stavu — bude-li to později třeba. Podkapitola Rewriting History popisuje několik užitečných triků, jak v systému Git přepsat historii a jak interaktivně připravovat soubory k zapsání. Než svou práci odešlete ostatním, použijte tyto nástroje k udržení čisté a srozumitelné historie.

Poslední věcí, na kterou byste měli myslet, jsou zprávy k revizím. Pokud si zvyknete připisovat k revizím kvalitní zprávy, bude pro vás práce s Gitem a spolupráce s ostatními mnohem jednodušší. Základním pravidlem je, že by vaše zprávy měly začínat jedním řádkem, který nemá víc než asi 50 znaků a který popisuje sadu provedených změn. Za ním následuje prázdný řádek a potom podrobnější vysvětlení. Projekt Git vyžaduje, aby podrobnější popis revize zahrnoval i vaši motivaci ke změnám a aby uvedl srovnání nové implementace s původním chováním. Tuto zásadu je dobré dodržovat. Doporučuje se také, aby se pro zápis zpráv používal rozkazovací způsob. Jinými slovy, formulujte je jako příkazy. Místo „Přidal jsem testy pro“ nebo „Přidány testy pro“ použijte „Přidej testy pro“. Zde je originální (přeložená) šablona, kterou napsal Tim Pope:

Pokud budou všechny vaše zprávy k revizím vypadat takto, usnadníte tím práci sobě i svým spolupracovníkům. Projekt Git obsahuje kvalitně naformátované zprávy k revizím. Zkuste spustit git log --no-merges, abyste se podívali, jak vypadá pěkně naformátovaná historie revizí projektu.

V následujících příkladech — a ve většině ukázek v knize — se takto pěkně naformátované zprávy nepoužívají kvůli stručnosti. Místo toho budeme používat volbu -m za příkazem git commit. Dělejte to, jak říkám, a ne jak to dělám.

Nejjednodušší situaci, s kterou se asi setkáte, představuje soukromý projekt s jedním nebo pár dalšími vývojáři. „Soukromý“ v této souvislosti znamená s uzavřeným zdrojovým kódem — okolní svět k němu nemá přístup. Vy a vaši ostatní vývojáři máte všichni oprávnění odesílat změny do repozitáře (push).

V takovém prostředí můžete uplatnit podobný pracovní postup, na jaký jste možná zvyklí ze systému Subversion nebo z jiného centralizovaného systému. Přesto získáte výhody v takových ohledech, jako je zapisování revizí offline a podstatně snazší větvení a slučování. Pracovní postup však bude velmi podobný. Hlavním rozdílem je to, že slučování probíhá na straně klienta, a ne během zapisování revize na straně serveru. Podívejme se, jak to může vypadat, když dva vývojáři začnou spolupracovat na projektu se sdíleným repozitářem. První vývojář, John, naklonuje repozitář, provede změny a zapíše lokální revizi. (V následujících příkladech byly zprávy protokolů nahrazeny třemi tečkami, abych je trochu zkrátil.)

Druhá vývojářka, Jessica, učiní totéž — naklonuje repozitář a zapíše provedenou změnu:

Jessica teď odešle (push) svou práci na server:

Také John se pokusí odeslat své změny na server:

John nemá povoleno odeslat změny, protože mezitím odeslala své změny Jessica. Pochopit to je obzvlášť důležité v případě, kdy jste zvyklí na Subversion. Můžete si totiž všimnout, že oba vývojáři neupravovali stejný soubor. Pokud byly upraveny různé soubory, provádí Subversion takové sloučení na serveru automaticky. Ale v Gitu musíte provést sloučení revizí (merge) lokálně. John musí vyzvednout (fetch) změny, které provedla Jessica, a začlenit je (merge) do své práce. Teprve potom mu bude umožněno je odeslat (push):

V tomto okamžiku vypadá Johnův lokální repozitář nějak takto:

John má k dispozici odkaz na změny, které odeslala Jessica, ale než bude moci sám odeslat svá data, bude muset začlenit její práci:

Sloučení probíhá hladce — Johnova historie revizí teď vypadá takto:

Teď může John svůj kód otestovat, aby se ujistil, že stále pracuje správně, a pak může odeslat svou novou sloučenou práci na server:

Johnova historie revizí nakonec vypadá takto:

Jessica mezitím pracovala na tématické větvi. Vytvořila tématickou větev s názvem issue54 a zapsala do ní tři revize. Zatím ještě nevyzvedla Johnovy změny, takže její historie revizí vypadá nějak takto:

Jessica chce synchronizovat svou práci s Johnem, a proto vyzvedne jeho data:

Tím stáhne práci, kterou mezitím odeslal John. Historie revizí Jessicy teď vypadá takto:

Jessica považuje svou tématickou větev za dokončenou, ale chce zjistit, co by měla do své práce začlenit, aby ji mohla odeslat. Spustí proto příkaz git log:

Zápis issue54..origin/master představuje filtr příkazu, kterým se Gitu říká, aby zobrazil seznam jen těch objektů revize, které se nacházejí v druhé z větví (zde origin/master), ale které se nenacházejí v první větvi (zde issue54). Podrobně se budeme touto syntaxí zabývat v části Commit Ranges.

Z výstupu vidíme, že existuje jediná revize, kterou zapsal John a kterou Jessica nesloučila se svou prací. Pokud začlení origin/master, bude to jediná revize, která změní její lokální práci.

Teď může Jessica začlenit svou tématickou větev do své větve master (merge), pak začlenit Johnovu práci (origin/master) rovněž do své větve master a potom může vše znovu odeslat na server (push). Nejdříve se přepne zpět na svou větev master, aby do ní mohla vše integrovat:

Buď může nejdříve začlenit origin/master nebo issue54. Obě revize jsou následníky té aktuální, takže na pořadí nezáleží. Konečný snímek bude stejný, ať zvolí jakékoli pořadí. Trochu se bude lišit jen historie revizí. Jessica se rozhodne začlenit nejdříve issue54:

Nevyskytly se žádné problémy. Jak vidíte, šlo o jednoduchý posun „rychle vpřed“. Nyní Jessica začlení Johnovu práci (origin/master):

Začlenění proběhne čistě a Jessičina historie bude vypadat následovně:

Větev origin/master je dosažitelná z Jessičiny větve master, takže by měla být schopná práci úspěšně odeslat (za předpokladu, že John mezitím neodeslal další revizi):

Každý z nich provedl několik zápisů (commit) a úspěšně začlenil práci toho druhého (merge).

Toto je jeden z nejjednodušších pracovních postupů. Po určitou dobu pracujete, obvykle na nějaké tématické větvi, a když je připravena k integraci, začleníte ji do své větve master. Chcete-li tuto práci sdílet, pak vyzvednete (fetch) a začleníte (merge) případné změny z origin/master do vaší větve master. Nakonec odešlete všechna data do větve master na serveru (push). Obvyklá posloupnost událostí vypadá takto:

V následujícím scénáři se podíváme na role přispěvatelů ve větší soukromé skupině. Naučíte se, jak pracovat v prostředí, v němž na jednotlivých úkolech spolupracují malé skupiny a tyto týmové příspěvky jsou poté integrovány jinou skupinou.

Řekněme, že John a Jessica spolupracují na jednom úkolu, zatímco Jessica a Josie pracují na jiném. Společnost v tomto případě používá typ pracovního postupu s integračním manažerem, kdy práci jednotlivých skupin integrují pouze někteří inženýři a větev master hlavního repozitáře mohou aktualizovat pouze oni. V tomto scénáři se veškerá práce provádí ve větvích jednotlivých týmů a později je spojována integrátory.

Sledujme pracovní postup Jessicy pracující na dvou úkolech a spolupracující v tomto prostředí paralelně s dvěma různými vývojáři. Protože už má naklonovaný repozitář, rozhodne se pracovat nejprve na úkolu featureA. Vytvoří si pro něj novou větev a udělá v ní kus práce:

V tomto okamžiku potřebuje sdílet svou práci s Johnem, a tak odešle revize své větve featureA na server. Jessica nemá oprávnění pro odesílání dat do větve master (ten mají pouze integrátoři), takže aby mohla s Johnem spolupracovat, musí své revize odeslat do jiné větve:

Jessica e-mailem Johnovi sdělí, že odeslala svou práci do větve pojmenované featureA a že se na ni může podívat. Zatímco čeká na zpětnou vazbu od Johna, rozhodne se, že začne pracovat spolu s Josie na úkolu featureB. Začne tím, že založí novou větev, která vychází ze serverové větve master:

Jessica nyní vytvoří několik revizí ve větvi featureB:

Jessičin repozitář vypadá nějak takto:

Je připravena odeslat svou práci, ale dostane e-mail od Josie, že již na server odeslala větev featureBee, v níž už je část práce hotová. Než bude Jessica moci odeslat svou práci na server, musí do ní nejprve začlenit práci Josie. Změny, které Josie provedla, vyzvedne příkazem git fetch:

Nyní může Jessica začlenit tyto změny do své práce příkazem git merge:

Tady nastává drobný problém. Musí odeslat sloučenou práci ze své větve featureB do větve featureBee na serveru. Může tak učinit příkazem git push s určením lokální větve, za níž bude následovat dvojtečka (:) a za ní vzdálená větev:

Říká se tomu refspec. Podrobnější diskusi o specifikaci gitových referencí a o různých možnostech práce s nimi najdete v kapitole The Refspec. Všimněte si též příznaku -u. Jde o zkratku pro volbu --set-upstream, která se používá k nastavení větví pro pozdější zjednodušené odesílání (push) a stahování (pull).

John poté pošle Jessice e-mail, aby jí sdělil, že odeslal několik změn do větve featureA, a poprosí ji, aby je ověřila. Jessica je stáhne spuštěním příkazu git fetch:

Poté si může příkazem git log prohlédnout, co všechno bylo změněno:

Nakonec začlení Johnovu práci do své vlastní větve featureA:

Jessica by ráda něco vylepšila, a proto vytvoří novou revizi a odešle ji zpět na server:

Historie revizí Jessicy bude nyní vypadat takto:

Jessica, Josie a John pošlou zprávu integrátorům, že větve featureA a featureBee jsou na serveru připraveny k integraci do hlavní linie. Poté, co integrátoři uvedené větve začlení do hlavní linie, bude možné vyzvednout (fetch) nový bod sloučení (merge commit) a historie revizí bude vypadat takto:

Mnoho skupin přechází na Git právě kvůli této možnosti paralelní spolupráce několika týmů a možnosti slučování různých linií práce až v pozdějších fázích procesu. Možnost spolupráce menších podskupin týmu prostřednictvím vzdálených větví — aniž by si práce vyžádala účast celého týmu nebo aby bránila ostatním v jiné práci — patří k obrovským výhodám Gitu. Posloupnost událostí ve zde popsaném pracovním postupu vypadá takto:

Přispívání do veřejných projektů je trochu odlišné. Protože nemáte oprávnění k tomu, abyste mohli aktualizovat větve projektu přímo, musíte svou práci správcům doručit nějakým jiným způsobem. První příklad popisuje, jak se přispívá s využitím odštěpení (fork) na gitovských hostitelských serverech, které podporují snadné vytváření odštěpených projektů. Tento mechanismus podporuje řada hostitelských serverů (včetně GitHub, BitBucket, Google Code, repo.or.cz a dalších) a řada správců projektů takový styl přispívání očekává. Další část pojednává o projektech, které upřednostňují přijímání záplat posílaných e-mailem.

Nejdříve pravděpodobně naklonujete hlavní repozitář, vytvoříte tématickou větev — pro záplatu nebo pro posloupnost záplat, kterými chcete přispět — a zde vaši práci zrealizujete. Posloupnost příkazů vypadá v podstatě takto:

Až budete s prací ve větvi hotovi a budete ji chtít poslat zpět správcům, přejděte na původní stránku projektu a klikněte na tlačítko „Fork“, čímž vytvoříte vlastní odštěpený projekt, do kterého budete moci zapisovat. Poté musíte URL adresu tohoto nového repozitáře přidat jako druhý vzdálený repozitář, v tomto případě pojmenovaný myfork:

Do něj teď musíte odeslat svou práci (push). Lepší bude, když do repozitáře odešlete svou tématickou větev (v které pracujete) než abyste výsledek začlenili do své větve master (merge) a odesílali tuto větev. Důvod je ten, že pokud nebude vaše práce přijata, nebo pokud z ní budou převzaty jen některé revize, nebudete muset svou větev master vracet zpět. Pokud správci provedou sloučení (merge), přeskládání (rebase) nebo částečné převzetí vaší práce (cherry-pick), budete stejně muset stáhnout změny z jejich repozitáře (pull):

Pokud jste práci odeslali do odštěpeného repozitáře, musíte to správci oznámit. Často se tomu říká „pull request“, čili požadavek na stažení. Můžete ho vytvořit prostřednictvím webové stránky — GitHub má svůj vlastní mechanismus Pull Request, kterým se budeme zabývat v kapitole GitHub — nebo můžete spustit příkaz git request-pull a správci projektu ručně zaslat výstup příkazu e-mailem.

Příkazu request-pull se zadává základní větev, do které chcete nechat vaši tématickou větev vtáhnout, a URL adresa gitového repozitáře, z kterého se má změna stahovat. Příkaz vypíše shrnutí všech změn, které by měly být vtaženy. Pokud chce například Jessica poslat Johnovi požadavek na stažení a vytvořila předtím dvě revize v tématické větvi, kterou právě odeslala, může zadat tento příkaz:

Výstup příkazu lze odeslat správci. Říká mu, odkud daná větev vychází, podá mu přehled o revizích a řekne mu, odkud lze práci stáhnout.

U projektů, kde nevystupujete jako správce, je většinou jednodušší, aby vaše větev master stále sledovala větev origin/master a abyste práci prováděli v tématických větvích, které můžete v případě odmítnutí snadno odstranit. Izolováním tématických úkolů do tématických větví si také usnadníte přeskládání vaší práce v případě, kdy se vrchol v hlavním repozitáři mezi tím posunul a vaše revize se už nedají čistě aplikovat. Pokud například chcete do projektu odeslat druhé pracovní téma, nepokračujte v práci v tématické větvi, kterou jste právě odeslali. Začněte znovu od začátku z větve master hlavního repozitáře:

Teď je každé z vašich témat obsaženo v samostatném zásobníku — podobá se frontě záplat — a můžete je přepsat, přeskládat a upravit, aniž by se obě témata navzájem ovlivňovala nebo aby se mezi nimi vytvářela vzájemná závislost, viz obrázek:

Řekněme, že správce projektu vtáhl do projektu několik jiných záplat a vyzkoušel vaši první větev, ale ta už se nedá začlenit čistě. V takovém případě můžete zkusit přeskládat tuto větev na vrchol větve origin/master, vyřešit za správce vzniklé konflikty a poté své změny ještě jednou odeslat:

Tím se vaše historie přepíše a bude vypadat jako na obrázku Historie revizí po přeskládání práce z featureA..

Protože jste větev přeskládali, musíte u příkazu pro odesílání (push) přidat -f, abyste mohli serverové větvi featureA podsunout revizi, která není jejím potomkem. Druhou možností by bylo odeslání nové práce na server do jiné větve (nazvané třeba featureAv2).

Podívejme se ještě na jeden možný scénář: Správce se podíval na práci ve vaší druhé větvi a tento koncept se mu líbí, ale rád by, abyste změnili jeden implementační detail. Této příležitosti využijete i k tomu, abyste za základ své práce vzali aktuální stav projektu ve větvi master. Začnete vytvořením nové větve z aktuální větve origin/master, nacpete (squash) do ní změny z featureB, vyřešíte případné konflikty, provedete požadovanou úpravu implementace a vše odešlete jako novou větev:

Volba --squash (stlačit) zajistí převzetí všech změn ze začleňované větve a stlačí je do podoby jedné sady změn, která vede ke stejnému stavu repozitáře, jako kdyby se provedlo opravdové sloučení (merge), ale nevytvoří se při tom bod sloučení^[16] (merge commit). To znamená, že váš budoucí objekt revize bude mít jen jednoho rodiče a přitom vám umožní vnést všechny změny z jiné větve a poté provést další úpravy ještě před tím, než se nová revize zapíše. V případě základního procesu slučování (merge) může být užitečná i volba --no-commit, která oddálí vytvoření bodu sloučení.

Teď už můžete správci zaslat zprávu, že jste provedli požadované změny a že je najde ve vaší větvi featureBv2.

Mnoho projektů si vytvořilo vlastní procedury pro přijímání záplat. Konkrétní pravidla si u každého projektu budete muset zjistit, protože budou odlišná. Protože existuje několik starších, větších projektů, kde se záplaty přijímají prostřednictvím vývojářské poštovní konference^[17], projdeme si teď podobný příklad.

Pracovní postup je podobný jako v předchozím případě. Pro každou sérii záplat, na níž pracujete, vytvoříte samostatnou tématickou větev. Odlišnost spočívá ve způsobu doručování změn do projektu. Místo vytváření odštěpeného projektu a odesílání změn (push) do vlastní zapisovatelné verze, vygenerujete e-mailovou verzi každé série revizí a pošlete je e-mailem do poštovní konference vývojářů:

Teď máte dvě revize, které chcete odeslat do poštovní konference. Pro vygenerování souborů v podobě vhodné pro zaslání poštou použijete příkaz git format-patch. Každá revize se tím přetransformuje na e-mailovou zprávu, jejíž předmět bude tvořit první řádek zprávy k revizi a tělo e-mailu bude tvořeno zbytkem zprávy a samotnou záplatou. Výhodou tohoto postupu je, že se při aplikaci záplaty z e-mailu, který byl vygenerován příkazem format-patch, korektně převezmou všechny informace o revizi.

Příkaz format-patch vypíše názvy souborů záplaty, kterou vytváří. Přepínač -M řekne systému Git, aby zkontroloval případné přejmenování. Soubory nakonec vypadají takto:

Do souborů se záplatami můžete dodatečně připsat další informace, které jsou určeny pro poštovní konferenci, ale které nechcete vkládat do zprávy k revizi. Pokud mezi řádek --- a začátek záplaty (řádek lib/simplegit.rb) přidáte nějaký text, mohou si ho vývojáři přečíst; ale při aplikaci záplaty se nepoužije.

Při odesílání souboru do poštovní konference můžete soubor buď vložit do svého poštovního programu, nebo ho můžete odeslat z příkazového řádku. Vkládání textu často způsobuje problémy s formátováním, zvlášť v případě některých „chytřejších“ klientů, kteří správně nezachovávají zalamování řádků a prázdné znaky (whitespace). Git naštěstí nabízí nástroj, který vám pomůže odeslat správně formátované záplaty protokolem IMAP, což pro vás může být jednodušší. Ukážeme si, jak se dá záplata odeslat přes Gmail, což je nástroj pro poštu, který známe nejlépe. Podrobné pokyny pro používání celé řady poštovních programů najdete na konci dříve zmíněného souboru Documentation/SubmittingPatches ve zdrojovém kódu systému Git.

Nejdříve si musíte ve vašem souboru ~/.gitconfig nastavit sekci „imap“. Každou hodnotu můžete nastavit zvlášť pomocí série příkazů git config, nebo můžete vložit hodnoty ručně. Na závěr by ale měl váš konfigurační soubor vypadat nějak takto:

Pokud váš server IMAP nepoužívá SSL, nebudou zřejmě dva poslední řádky vůbec třeba a hodnota hostitele bude imap://, a nikoli imaps://. Až toto nastavení dokončíte, můžete použít příkaz git imap-send, jímž umístíte sérii záplat (patch) do složky Drafts zadaného serveru IMAP:

V tomto okamžiku byste měli být schopni přejít do své složky Drafts, změnit pole To na adresu poštovní konference, do které záplatu posíláte, případně pole CC na správce nebo na osobu odpovědnou za tuto část, a odeslat.

Záplaty můžete odesílat i přes SMTP server. Můžete rovněž nastavit každou hodnotu zvlášť sérií příkazů git config, nebo je můžete vložit ručně do sekce sendemail vašeho souboru ~/.gitconfig:

Jakmile je to hotové, můžete záplaty odeslat příkazem git send-email:

Git poté vytvoří log s určitými informacemi, který bude pro každou odesílanou záplatu vypadat asi takto:

Tato část se zabývala obvyklými pracovními postupy, které týkají několika velmi odlišných typů gitových projektů, s kterými se asi setkáte. Uvedla pár nových nástrojů, které vám pomohou celý proces zvládnout. V další části uvidíte, jak se pracuje na druhé straně — jak se spravuje gitový projekt. Dozvíte se, jak být benevolentním diktátorem nebo integračním manažerem.