Průběhy práce v Mercurialu

V Mercurialu lze realizovat mnoho různých vývojových schemat. V tomto textu se s některými seznámíme, přičemž budeme postupovat od jednodušších ke složitějším. Účelem této pomůcky je usnadnit začátečníkům práci se sledováním verzí (verzování). Použité pojmy nejsou vždy vysvětlovány, neboť existuje řada jiných výtečných textů (Základní pojmy Mercurialu a Behind the scenes), které tak činí.

Podrobnější popis se základními pojmy naleznete v tutorialu o používání Mercurialu - Tutorial Mercurialu. Opravdu podrobný a velmi čtivý popis Mercurialu obsahuje kniha B. O´Raillyho Mercurial:The Definitive Guide.

<!> Tento průvodce nevyžaduje žádnou předchozí znalost VCS (Version Control Systems). Zkušenosti s příkazovým řádkem terminálu budou prospěšné, protože jej budeme používat.

Základní průběhy

Osamělý vývojář s lineární historií

Popis případu

První průběhové schema je nejsnadnější. Chceme zaznamenávat změny a mít možnost se kdykoliv ke kterékoliv vrátit.

Průběh

Jako první krok bychom měli zadat své jméno. V textovém editoru otevřeme soubor ~/.hgrc (případně mercurial.ini), přidáme sekci ui (user interaction) a zapíšeme jméno uživatele:

 [ui]
 username = Mr. Johnson <hali@beli.cz>

Nyní vytvoříme adresář projektu, ve kterém budeme pracovat:

 $ hg init baboon        

Přejdeme do adresáře, vytvoříme nějaké soubory a přidáme je ke sledování:

 $ cd baboon
 $ echo `print "Hello"` > hello.py
 $ hg add

<!> Můžeme také vstoupit do existujícího adresáře se soubory a tam vytvořit složku (repozitář) .hg:

 $ cd project
 $ hg init

Případně můžeme přidat ke sledování jenom určité soubory místo všech souborů v adresáři. Následujícím příkazem například přikážeme sledování souborů file10, file11 a file12:

 $ hg add file10 file11 file12 

Přidané soubory se staly "kandidáty pro registraci". Vlastní zápis změn do repozitáře provádíme jejich předáním příkazem commit:

$ hg commit

Vyskočí textový editor a žádá si zápis komentáře komitu. Po uložení a zavření editoru máme změny předané.

<!> Komentář komitu lze zadat zároveň s jeho příkazem (zde zkráceným):

 $ hg ci -m "Komentář"

Přítomnost nekomitovaných změn v pracovním adresáři zjistíme příkazem:

 $ hg status

případně rozdíl mezi dvěmi verzemi souboru:

 $ hg diff

Při přemístění a kopírování souborů pomocí příkazů Mercurialu (cp, mv) nemusíme tyto změny "uvádět na kandidátskou listinu" pomocí příkazů hg add, hg remove nebo hg addremove. Nezapomeneme však předat změny repozitáři, to jest provést příkaz commit:

 $ hg cp orig kopie
 $ hg ci -m "stručný komentář"
 
 $ hg mv orig sloha/rupie  # přemístit lze jen uvnitř kořenového adresáře
 $ hg ci -m "sloha je název adresáře"

Máme nyní dva nové soubory 'kopie' a 'rupie' a Mercurial o nich ví.

Výpis seznamu všech zaznamenaných změn vyvoláme příkazem:

 $ hg log

Informace o changesetu (revizi) obsahuje ID, jméno komitenta, datum a čas komitu a komentář.

Pokud nás zajímá jenom určitá revize, použijeme přepínač -r (--revision). Aby se nám také zobrazil diff určené revize, přidáme přepínač -p (--patch):

 $ hg log -p -r 3

Osamělý vývojář s větvenou historií

Popis případu

Druhé průběhové schema je stále velmi jednoduché: jste sám a chcete aby Mercurial zaznamenával vaše změny, přičemž je možné, že se budete chtít někdy vrátit ke starší verzi (souboru) a dodatečně ji upravit.

Průběh

Otevření nového projektu, případně založení nového repozitáře, případně další práci v pracovním adresáři provádíme známým způsobem:

 $ hg init projekt
 $ cd projekt
 $ (přidáme soubory)
 $ hg add                    # zařadíme je ke sledování
 $ (provedeme nějaké změny)
 $ hg diff                   # prohlédneme si je
 $ hg ci -m "zápecí"         # předáme je repozitáři
 $ hg cp copak kampak        # kopírujeme soubory či složky
 $ hg mv copak kampak        # přemístíme soubory či složky
 $ hg ci -m "párátko"
 $ hg log                    # prohlédneme si historii

Návrat ke starší revizi

Tím, že jsme v našem adresáři vytvořili systémový adresář (repozitář) .hg, učinili jsme z našeho pracovního adresáře "vnímavý útvar", jehož skladba a obsah jeho souborů se mění v závislosti na nastavené aktuální revizi.

Implicitně je touto revizí revize poslední, nazývaná tip. K libovolné jiné revizi se dostaneme příkazem hg update REV, přičemž REV je pořadové číslo revize. Poslední revizi zas můžeme aktualizovat (zkráceně) příkazem hg up tip

Která revize je právě aktuální, se dozvíme příkazem hg identify -n, kde si přepínačem n říkáme o pořadové číslo revize.

Příkaz identify bez přepínače nám vrátí zkrácený tvar ID. Na rozdíl od pořadového čísla revize, které pro tentýž changeset může být v každém repozitáři jiné, se toto číslo nemění. Pořadové číslování revizí začíná nulou.

Je-li aktuální poslední revize, hg identify -n vrátí -1.

Oprava starších chyb

Opravou chyby ve starší revizi vytvoříme v repozitáři další čelo (head), které musíme sloučit s čelem stávajícím:

 $ hg update 3              # tam máme čertovo kopýtko
 $ (opravíme chybu)
 $ hg commit

Oprava chyby je "zaknihována", ještě sloučíme čela:

 $ hg merge

Pokud by se při sloučení vyskytl problém, použijeme příkaz hg resolve - tak, jak jsme případně programem vybízeni.

Nejprve dáme vypsat seznam konfliktních souborů:

 $ hg resolve --list

Potom je jeden po druhém řešíme. Příkaz resolve se opět pokusí o sloučení:

 $ hg resolve konfliktni_soubor
 (případně upravíme konflikt ručně)

Upravený soubor označíme jako řešený

 $ hg resolve --mark conflicting_file

Jakmile vyřešíme všechny konflikty, provedeme commit! Ten ostatně provedeme i když se žádné konflikty nevyskytly.

 $ hg commit

V této chvíli máme opravu sloučenou s ostatní naší prací, ve které můžeme pokračovat. Zaznamenaná historie nám jasně ukazuje, kde chyba vznikla a kdy byla opravena.

<!> Když opravíme chybu souboru ve starší revizi a v nějaké pozdější revizi byl tento soubor kopírován nebo přemístěn, bude tato oprava sloučením rozšířena do cílových souborů. To je hlavní důvod, proč bychom kopírování a přemísťování souborů uvnitř pracovního adresáře měli provádět pomocí příkazů Mercurialu hg cp a hg mv.

Oddělený vývoj

Popis případu

Někdy pracujeme současně na několika variantách jednoho programu. Chceme-li se vyhnout náhodnému pomíchání nehotových verzí kódu, můžeme vytvořit klon lokálního repozitáře a pracovat na variantách v jejich vlastních pracovních adresářích.

Po dokončení stáhneme (pull) variantu do hlavního adresáře a sloučíme (merge) ji s lokálními změnami.

Průběh

Práce s klonem

Nejprve vytvoříme klon a v něm nějaké změny:

 $ hg clone baboon makak
 $ cd makak
 $ (provedeme změny a komity)

Nyní si ověříme, co obdržíme, když provedeme pull z adresáře makak (podobně jako používáme příkaz diff před komitem). Příslušný příkaz pro to je incoming (příchozí):

 $ cd ../baboon
 $ hg incoming ../makak

<!> Kdybychom chtěli vidět i diffy, použijeme přepínač hg incoming --patch stejně jako použijeme tento přepínač (hg log --patch) při zjišťování změn v repozitáři.

Pokud se nám změny zamlouvají, stáhneme je do hlavního adresáře projektu:

 $ hg pull ../makak

Změny jsme si z adresáře makak stáhli, ale v adresáři baboon je zatím nevidíme. Jsou uloženy v repozitáři .hg (viz Za kulisami).

Pokud jsme v adresáři baboon žádné změny neprovedli, stačí nám po stažení změn z adresáře makak provést pouze hg update tip, to jest aktualizovat pracovní adresář k novému tipu. Je však více než pravděpodobné, že jsme si v baboon změny provedli; v tom případě je nutné sloučit stažené změny se změnami lokálními:

 $ hg merge

Pokud jsou konflikty, provedeme hg resolve. Po sloučení musíme provést commit, aby se naše úpravy zapsaly do repozitáře:

 $ hg ci -m "připojený makak"

<!> Lze provést libovolný počet klonů a nosit je po kapsách na tyčinkách USB.

<!> Příkaz commit musíme zadat i po nekonfliktním sloučení, protože tím tuto změnu zapisujeme do historie.

Odvolání chyb

Někdy se nám podaří provést špatný komit. Pokud to zjistíme dřív, než provedeme další komit nebo pull, můžeme tuto zmýlenou snadno napravit příkazem rollback (odvolat):

 hg rollback

Podle přísloví "dobrého pomálu" nelze provést rollback dvakrát bezprostředně za sebou. Příkaz rollback lze použít také pro odvolání příkazu pull, pokud jsme poté neprovedli komit.

<!> Podobně pracuje pro nekomitovanou změnu příkaz hg revert

Sdílení změn

Popis případu

Nyní postoupíme o krok dále: Již nejsme sami a chceme své změny sdílet s ostatními.

V Mercurialu můžeme tuto spolupráci realizovat prostřednictvím lokálního serveru, posíláním změn e-mailem nebo s využitím veřejně přístupného webového serveru.

Použití lokálního serveru

Aktivací vestavěného lokálního serveru na portu 800 umožníme ostatním na síti přístup do našeho počítače:

 $ hg serve

Zkusme nyní ve vlastním webovém serveru zadat adresu http://localhost:8000/. Otevře se nám stránka s pěkným přístupem k tomu repozitáři, u kterého byl server aktivován.

Všichni ostatní se k našemu serveru dostanou, pokud znají naši IP adresu (např 192.168.178.100)

 $ firefox http://192.168.178.100:8000

Mohou si z našeho repozitáře stáhnout poslední změny:

 $ hg pull http://192.168.178.100:8000

Z bezpečnostních důvodů je možné přes tento server provádět pouze pull, nikoliv push.

Posílání změn e-mailem

Může se stát, že nemáte přístup k cizímu repozitáři; ten je buď odstíněn bezpečnostním firewallem nebo se nachází v jiném časovém pásmu. Důvodů pro tento způsob přenosu změn může být celá řada.

Změny pošleme jako specielní oprávkové soubory s příponou .diff.

Nejprve se podíváme, co vlastně chceme poslat:

 $ cd project
 $ hg log

Řekněme, že chceme poslat revize 3 a 4. Oprávkové soubory .diff vytvoříme pomocí příkazu 'hg export':

 $ hg export 3 > change3.diff
 $ hg export 4 > change4.diff

Soubory pošleme e-mailem. Příjemce si změny může importovat do svého repozitáře. Když bude opatrný, vytvoří si za účelem příjmu cizích změn klonovaný repozitář, do něhož změny načte:

 $ hg clone project integration
 $ cd integration
 $ hg import change3.diff
 $ hg import change4.diff

Po patřičné kontrole si importované změny stáhne do svého hlavního repozitáře:

 $ cd ../project
 $ hg pull ../integration

<!> Velmi efektní způsob přenosu změn v souboru je pomocí tak zvaného svazku (bundle) - viz hg help bundle.

Použití společného repozitáře

Společný repozitář si vytvoříme na kolektivně přístupném privátním nebo veřejném serveru. Veřejných serverů je celá řada. Vyjmenujeme-li alespoň dva, zmíníme BitBucket a Launchpad. Posledně jmenovaný je podporován konkurenčním VCS, zvaným 'Bazaar'.

Základním pravidlem dobrého chování je to, že u takového repozitáře nevytváříme dvě čela.

Znamená to, že chceme-li poslat své změny do centrálního repozitáře, provedeme nejprve akci pull a ve svém repozitáři vyřešíme případné konflikty a provedeme sloučení. Takto synchronizovanou změnu potom příkazem push můžeme vyslat do centrálního repozitáře.

U centrálních repozitářů lze nastavit různou přístupovou politiku.

Popíšeme si podrobněji postup na serveru BitBucket, kde se zapíšeme jako uživatel.

Po přihlášení si vytvoříme nový repozitář tak, že přejedeme kurzorem přes nápis Repositories a vybereme Create new. Zadáme nazev repozitáře a popis jeho účelu. Chceme-li uzavřít přístup široké veřejnosti, označíme jej jako private.

Poté v repozitáři poklepneme na záložku Admin, kde můžeme v části Permissions:Readers a Permissions:Writers zapsat uživatelská jména svých kolegů, čímž jim umožníme provádět push do našeho repozitáře.

Řekněme, že naše uživatelské jméno je "ozon" a název repozitáře je "foo". Potom adresa našeho repozitáře bude https://bitbucket.org/ozon/foo.

Při volání našeho repozitáře (například)

$ hg incoming https://bitbucket.org/ozon/foo

jsme žádání o zadání uživatelského jména a hesla pro bitbucket.

S tímto repozitářem zacházíme stejně jako s lokálním repozítářem. Můžeme si z něho pořídit také lokální kopii (hello):

 $ hg clone https://bitbucket.org/ozon/foo/ hello

Do konfiguračního souboru naklonovaného repozitáře se automaticky načte adresa on-line repozitáře, takže ji při jeho volání nemusíme zadávat.

<!> Variantně lze dohodnout, že každý člen kolektivu má na bitbucket otevřený svůj repozitář, do kterého posílá své změny. Určený administrátor potom tyto změny podle svého uvážení stahuje do centrálního repozitáře, z něhož si ostatní aktuální změny stahují.

<!> You can also use this workflow with a shared server instead of bitbucket, either via SSH or via a shared directory. An example for an SSH URL with Mercurial is be ssh://user@example.com/path/to/repo. When using a shared directory you just push as if the repository in the shared directory were on your local drive.

Shrnutí

Jak bylo již řečeno na začátku, tento text nevysvětluje podrobnosti, což je někdy právě to, co potřebujeme. Můžeme-li trochu anglicky, je dobré zkusit nápovědu k jednotlivým příkazům

$ hg help <příkaz>

Popsané postupy si ještě stručně připomeneme.

založit projekt

 $ hg init project
 $ cd project
 $ (přidat nějaké soubory)
 $ hg add
 $ hg commit
 (napsat komentář komitu)

větvený průběh

 $ (proveď nějaké změny)
 $ hg commit
 (napiš komentář komitu)
 $ hg update 0
 $ (proveď nějaké změny)
 $ hg commit
 (napiš komentář komitu)
 $ hg merge
 $ (případně s použitím hg resolve)
 $ hg commit
 (napiš komentář komitu)

rozdělení do klonů

 $ cd ..
 $ hg clone project feature1
 $ cd feature1
 $ (proveď nějaké změny)
 $ hg commit
 (napiš komentář komitu)
 $ cd ../project
 $ hg pull ../feature1

využití integrovaného serveru

 $ hg serve 
 $ cd ..
 $ hg clone http://127.0.0.1:8000 project-clone

export změn do souboru

 $ cd project-clone
 $ (proveď nějaké změny)
 $ hg commit
 (napiš komentář komitu)
 $ hg export tip &gt; ../changes.diff

import změn ze souboru

 $ cd ../project
 $ hg import ../changes.diff

stáhnout změny přes integrovaný server

 $ cd ../feature1
 $ hg pull http://127.0.0.1:8000

použití společného repozitáře na BitBucket

 $ (setup bitbucket repo)
 $ hg push https://bitbucket.org/USER/REPO
 (zadat jméno a heslo)
 $ hg pull https://bitbucket.org/USER/REPO

Pokročilé průběhy

Anulování špatných revizí

Popis případu

Při stahování kódu z jiných repozitářů se může stát, že přehlédneme chybný changeset. Poté, co si jej jiní od nás stáhli, máme malou šanci, že se jej někdy úplně zbavíme.

Pro řešení tohoto problému nabízí Mercurial příkaz backout. Tento příkaz vytváří nový changeset, který je dítětem anulovaného changesetu. Záznam špatného changesetu v historii nezrušíme, ale můžeme jej odebrat z nových revizí.

<!> Základní příkazy Mercurialu historii nepřepisují. Máme-li takovou potřebu, musíme aktivovat některou extenzi, která je součástí instalace. K tomuto tématu se vrátíme později.

Průběh

Řekněme, že špatnou změnou byla revize 3. Špatný kód se pokusíme odstranit příkazem backout. Tím vytvoříme novou změnu, která vytěsní tu starou. Protože provádíme změnu starší revize, vytvoříme další čelo, které musíme sloučit se stávajícím.

 $ hg backout 3
 $ hg merge
 (případně vyřešíme konflikty)
 $ hg commit
 (komentář komitu, např: "merged backout")

A je to. Odvolali jsme špatnou změnu. Je stále zaznamenáno, že existovala (podle zásady "nepřepisovat historii, pokud to není nezbytné"), ale již neovlivňuje budoucí kód.

Kolektivní vývoj variant

Nyní, když si umíme předávat změny a v případě potřeby je anulovat, můžeme postoupit dále: pomocí Mercurialu koordinovat vývoj kódu.

Popis případu

Chceme-li rozdělit náš projekt do několika variant, potřebujeme vědět, na čem kdo pracuje a kde se jeho práce ukládá.

Mercurial to umožňuje svými "pojmenovanými větvemi". Ty jsou součástí hlavního repozitáře, takže jsou přístupné každému účastníkovi. Zároveň se změny komitované v pojmenované větvi nemísí se změnami v hlavní (default) větvi.

Průběh

Když někdo v naší skupině chce začít pracovat na variantě tak, aby nerušil ostatní, může vytvořit pojmenovanou větev a své změny ukládat zde. Když se někdo chce připojit, nic mu nebrání; připojuje své změny na konec větve. Po ukončení vývoje varianty lze pojmenovanou větev sloučit s hlavní větví.

Práce v pojmenované větvi

Vytvoření pojmenované větve:

 $ hg branch ferari     
 (proveď nějaké změny)
 $ hg commit            # větev se nadál jmenuje ferari
 (napiš komentář komitu)

Můžeme používat příkazy commit, pull, push, merge, ... jako kdybychom pracovali v samostatném repozitáři.

 $ hg update default    # nás přenese k poslední revizi před 'ferari'
  ...
 $ hg update ferari     # nás vrátí k poslední revizi větve 'ferari'

Sloučení pojmenované větve

Po ukončení alternativního vývoje pojmenovanou větev ukončíme sloučením.

 $ hg update default
 $ hg merge ferari
 $ hg commit
 (napiš komentář komitu)

<!> Ukončená pojmenovaná větev je natrvalo zapsaná do historie. Pokud ji tam mít nechcete, lze to řešit způsobem, popsaným ve Workflows.

Označování revizí

Popis případu

Pro označení revizí uživatelem se v Mercurialu používají tagy. Připojení tagu k revizi lze provést i dodatečně. Zadání tagu vytváří samostatný changeset generovaný automatickým komitem se standardním koomentářem.

<!> Tag nesmí obsahovat znak ":", protože tento znak se používá pro vymezení rozsahu revizí - viz "hg help revisions".

<!> K bezpečnému označení revizí lze použít gpg extenzi.

Průběh

Řekněme, že cheme revizi 3 dát jméno otto

Přidáme tag:

 $ hg tag -r otto

Prohlédneme si všechny tagy:

 $ hg tags

Když se podíváme na záznam (log), uvidíme v revizi 3 další řádek s názvem tagu. Chceme-li aktualizovat pracovní adresář k označené revizi, použijeme její tag:

 $ hg update otto

Odstranění historie

Popis případu

Někdy máme v repozitáři změny, které nepotřebujeme a chtěli bychom je odstranit.

Tento problém lze řešit více způsoby s použitím extenze (Mercurial Queues). My si ukážeme řešení prostřednictvím příkazů, které jsme spolu poznali.

Tento pracovní postup není ale vhodný, pokud potřebujeme odstranit velmi zasuté změny.

Průběh

Řekněme, že se chceme zbavit předposlední revize 2.

Vytvoříme klonovaný repozitář s revizemi 0 až 1. Revizi 3 exportujeme jako oprávku do klonovaného repozitáře, kterou tam posléze importujeme:

 $ hg clone -r 1 baba bubu
 
 $ cd baba
 $ hg export 3 > ../bubu/rev3.diff
 
 $ cd ../bubu
 $ hg import rev3.diff
 $ hg add                # adding rev3.diff
 $ hg ci -m "Adieu"

V repozitáři bubu došlo k přečíslování; máme revize 0 až 4. Původní revize 2 je pryč, komentář poslední revize je "Adieu". Repozitář baba zůstává beze změny.

Pokud část změn nejde použít, uloží se do souboru *.rej. Tyto změny musíme sami připojit nebo je odvrhnout.

 $ cat *.rej                # vypíše obsah souboru  
 (rozhodneme o změnách)
 $ hg commit
 (napiš komentář komitu)

<!> Pokud jsme revizi 2 před odstraněním někomu poslali, může se stát, že si ji opět stáhneme.

Závěrečné poznámky

Popisy dalších průběhů lze nalézt na již zmiňované stránce Workflows.

Autorem originálního textu "Learning Mercurial in Workflows" je Arne Babenhauserheide. Text je chráněn licencí GPLv2