Tento průvodce vám ukáže jak lze použít Mercurialu pro komunikaci se vzdálenými repozitáři přes HTTP a SSH.
Obsah
V části Základy Mercurialu jste viděli jak si Alenka s Bobem mohou vzájemně posílat a stahovat změny v témže souborovém systému. Taková situace je pohodlná, ale většina uživatelů takový přímý přístup nemá. Proto Mercurial podporuje vzdálený přístup přes síťové připojení.
Mercurial ovládá dva síťové protokoly:
HTTP: protokol používaný normálními webovými servery
Mercurial přichází s malým vestavěným webovým serverem, který můžete spustit příkazem hg serve a který vám umožní brouzdání historií repozitáře ve vašem webovém prohlížeči. Pro náročnější použití se doporučuje skript hgweb.cgi.
SSH: bezpečný protokol rozhranní (shell), používaný mnoha Unixovými systémy.
Máte-li již účet SSH na serveru s nainstalovaným Mercurialem, potom použití SSH je nejsnadnější cesta ke klonování repozitáře. Je možné nastavit účet s omezeným přihlašovacím prostředím, takže uživatelé mohou provádět pouze ty příkazy, které souvisí s Mercurialem. Viz skript hg-ssh s podrobnějšími informacemi.
Podíváme se nejprve, jak lze komunikovat s repozitáři přes HTTP. Tento protokol je velmi populární, protože dobře integruje většinu existujících podnikových infrastruktur: máte-li fungující webový server přístupný přes port 80, potom máte vše, co potřebujete pro připojení repozitářů Mercurialu.
Nechť Alena pro začátek provede klon malého repozitáře s příklady:
alice$ hg clone https://bitbucket.org/aragost/hello destination directory: hello requesting all changes adding changesets adding manifests adding file changes added 1 changesets with 1 changes to 1 files updating to branch default 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
Jak lze vidět, neliší se to příliš od způsobu, kterým Alenka klonovala repozitář s použitím cesty v systému souborů; v obou případech je výsledkem úplná kopie repozitáře s vybranou větví default.
Lokálníh klon umí Mercurial vytvořit mnohem rychleji, než klonu přes HTTP. Není to jenom proto, že načítání dat přes síť je pomalejší než z lokálního disku, ale i proto, že lokální klon opakovaně využívá prostor v adresáři .hg s použitím hardlinků mezi soubory. Dva klony takto sdílejí prostor na disku, zabraný dvěma adresáři .hg a pouze jednou pracovní kopií repozitáře.
Alenka nyní může ve svém klonu provádět vlastní komity:
alice$ cd hello alice$ echo "Hello, World!" > hello.txt alice$ hg commit -m "Add comma"
Toto je podstata necentralizované správy revizí — Alenka si může vytvořit nezávislou kopii repozitáře a lokálně na ní pracovat. Svůj klon může porovnávat se vzdáleným serverem.
alice$ hg outgoing comparing with https://bitbucket.org/aragost/hello searching for changes changeset: 1:61c1daa1d929 tag: tip user: Alice <alice@example.net> date: Sat Jan 22 10:00:00 2011 +0000 summary: Add comma
Nemůže ale poslat svůj changeset na server, protože na tomto serveru nemá právo zápisu do tohoto určitého repozitáře.
Jak již bylo zmíněno dříve, Mercurial má vestavěný webový server. Ten lze použít k rychlému sdílení repozitáře s jiným počítačem v síti LAN nebo dokonce pro brouzdání v historii revizí.
Nechť Alenka nabídne (serve) svůj klon repozitáře hello:
alice$ hg serve listening at http://localhost:8000/ (bound to 127.0.0.1:8000)
Repozitářem lze nyní brouzdat v normálním webovém prohlížeči na adrese http://localhost:8000/. Zde uvidíme historii projektu s lineárním grafem, můžeme prohlížet jednotlivé changesety, seznamy tagů a větví, můžeme anotovat soubory a vyjmout kteroukoliv revizi jako tarball nebo komprimovaný soubor. Jinými slovy, vestavěný webový server je velice vhodný nástroj jak pro lidi, tak pro počítače :-).
Bob si může vytvoři klon Alenčina repozitáře:
bob$ hg clone http://localhost:$HGPORT hello requesting all changes adding changesets adding manifests adding file changes added 2 changesets with 2 changes to 1 files updating to branch default 1 files updated, 0 files merged, 0 files removed, 0 files unresolved bob$ cd hello bob$ cat hello.txt Hello, World!
Pokud Bob provede nějaké změny a pokusí se je poslat zpět, setká se s následujícím chybovým hlášením:
bob$ hg push pushing to http://localhost:8000/ searching for changes remote: ssl required remote: ssl required updating 61c1daa1d929 to public failed!
Stane se to, že webový server Mercurialu vás implicitně nenechá poslat změny přes HTTP bez zadání HTTPS URL. Alenka může zneplatnit tento požadavek použitím opce --config web.push_ssl=No při nabízení (serve) repozitáře. Nejprve zlikviduje starý proces hg serve a potom spustí nový:
alice$ hg serve --config web.push_ssl=No listening at http://localhost:8000/ (bound to 127.0.0.1:8000)
Když to Bob zkusí znova, setká se s novou chybou, protože repozitáře jsou implicitně v režimu ‘jen ke čtení’.
bob$ hg push pushing to http://localhost:8000/ searching for changes abort: authorization failed
Všimněte si, že Bobovo poslání (push) bylo zrušeno, aniž by Bob dostal šanci zadat uživatelské jméno či heslo. Důvodem je to, že vestavěný webový server nepodporuje autentifikaci, neboť není vybaven správou uživatelů. U tohoto serveru se nepředpokládá, že bude používan v širším prostředí. Pro připojení k www použijete skript hgweb.cgi, dodávaný s Mercurialem, který spustíte v opravdovém webovém serveru, jako je např. Apache. Tento webový server má potřebnou infrastrukturu pro řádné ověření uživatele. Výhodou tohoto nastavení je to, že pro ověření můžete použít svou preferovanou metodu: máte-li nastavení, ve kterém ověřujete uživatele proti databázi LDAP, potom jej použijete i pro Mercurial.
V našem příkladu necháme Alenu vypojit ověřovací proces ještě další opcí příkazu:
alice$ hg serve --config web.push_ssl=No --config "web.allow_push=*" listening at http://localhost:8000/ (bound to 127.0.0.1:8000)
Nyní Bob může poslat svůj changeset zpátky Alence:
bob$ hg push pushing to http://localhost:8000/ searching for changes remote: adding changesets remote: adding manifests remote: adding file changes remote: added 1 changesets with 1 changes to 1 files
Zde se žádné ověřování neprovádělo, ale ve většíně reálných případů budete muset provést autentifikaci nejen pro posílání changesetů ale někdy i pro jejich stahování. Otázku caching of HTTP(S) credentials probereme dále.
Přistoupíme-li k repozitáři pomocí skriptu hgweb.cgi, potom tento přístup je vlastně realizován webovým serverem pro který musíme mít potřebné oprávnění k zápisu, abychom mohli na tomto serveru publikovat svůj repozitář.
Když lidé posílají změny přes HTTP, dostává se ke slovu proces webového serveru, který zapíše nové soubory do adresáře hg. Jména uživatelů, vložená do changesetů zde nehrají žádnou roli.
Dalším síťovým protokolem, podporovaným Mercurialem, je SSH. Mercurial se při použití URL SSH připojí k serveru a vytvoří tunel SSH mezi svými dvoumi procesy. Tyto procesy potom spolu komunikují při posílání a stahování changesetů.
Z toho vyplývá, že účet pro SSH server není potřebný. Mnozí administrátoři budou ale dávat přednost sestavě založené na HTTP, protože ta je váže k jejich existující sestavě webového serveru.
Ovšem, máte-li učet na serveru a je-li na systému nainstalovaný Mercurial, potom je protokol SSH velmi snadno použitelný. Nutno si pamatovat pouze to, že syntaxe je syntaxí URL a nikoliv záležitostí cesty SSH - scp nebo rsync`. Takže napíšete:
$ hg clone ssh://server/path/to/repository
nikoliv:
$ hg clone server:path/to/repository
Pamatujte také, že path/to/repozitory je relativní k vašemu domovskému adresáři na serveru. Chcete-li na serveeru použít absolutní cestu, potom napíšete URL nějak takto:
$ hg clone ssh://server//absolute/path/to/repository
První lomítko je část syntaxe URL, druhé lomítko je částí cesty na serveru, takže výše uvedený URL najde /absolute/path/to/repository na serveru.
Na rozdíl od HTTP URL, lze SSH URL použít jako cíl pro hg clone. Takže můžete psát:
$ hg clone . ssh://server/path/to/repository
za účelem klonování aktuálního repozitáře na server.
Protože se Mercurial přihlašuje k serveru, musí mít uživatel oprávnění na serveru číst, aby mohl stahovat changesety nebo provádět klony. Podobně musí mít oprávnění k zápisu na serveru aby mohl posílat (push) changesety zpět.
Pokud se při posílání změn přes SSH vyskytne chyba, zkuste přidat --debug k vysílacímu příkazu a pozorujte odezvu Mercurialu. Zkuste se přihlásit přes SSH se stejným jménem uživatele a ověřte si, zda máte přístup k souborům.
Při komunikaci s webovým serverem se může objevit prompt pro zadání jména a hesla uživatele:
$ hg clone https://bitbucket.org/aragost/private http authorization required realm: Bitbucket.org HTTP user: aragost password: <secret> abort: http authorization required
Provádět autentifikaci pro každý příkaz (hg clone, hg pull, hg push, hg incoming, hg outgoing), posílaný na vzdálený repozitář se může stát brzy únavné. Existuje několik způsobů pro uložení osobních údajů v Mercurialu. Probereme je podle pořadí důležitosti.
Tip
Uložit v Mercurialu ověřovací frázi (passphrase) pro SSH nelze. Autentizace SSH je pro Mercurial externí záležitostí pro kterou je nutno použít standardního agenta SSH.
SSH Agent je program, který běží na pozadí a uchovává v paměti dešifrovanou verzi vašeho privátního klíče pro SSH. Kdykoliv potřebujete provést SSH spojení, zeptá se program SSH Agenta, má-li vhodný dešifrovaný privátní klíč. Pokud ano, uskuteční se spojení bez vašeho zásahu, v opačném případě vás ssh požádá o heslo jako normálně.
Svůj klíč zadáte do SSH Agenta pomocí ssh-add v Linuxu a Mac OS X; ve Windows použijete Pageant programu Putty.
In short:
Pros: passwords are stored in a OS-specific secure backend, most secure option.
Cons: requires third-party extension.
Extenze keyring vytvoří háček pro Mercurial a vstoupí do cesty dotazu na hesla. Zadaná hesla jsou potom bezpečně uložena ve specifické databázi OS a není zapotřebí je opětovně zadávat. Uložena jsou hesla pro HTTP(S) ověření a SMTP ověření (jak mezi jinými činí extenze patchbomb).
Toto je standardní řešení při použití TortoiseHg ve Windows, neboť tato aplikace obsahuje potřebnou extenzi i knihovnu pro komunikaci s heslem na pozadí. V jiných systémech si musíte vhodné knihovny nainstalovat sám.
In short:
Pros: standard feature in Mercurial. Makes it easy to setup the password used for all repositories on a given host.
Cons: passwords are stored in a plaintext configuration file. Care must be used if the file is shared with others.
Přihlašovací údaje lze uložit také přímo do konfiguračního souboru Mercurialu. Provedete to pomocí sekce auth:
[auth] bb.prefix = https://bitbucket.org/ bb.username = alice bb.password = <secret>
Sekce [auth] obsahuje řadu vstupů, seskupených podle zvoleného klíče. Výše jsme použili bb jako klíč pro Bitbucket. Máte-li víc míst, pro které potřebujete uložit hesla, můžete pro každého hostitele použít různý klíč:
[auth] site-a.prefix = https://hg.site-a.net/ site-a.username = userA site-a.password = <secret-a> site-b.prefix = https://site-b.org/repos/ site-b.username = userB site-b.password = <secret-b>
In short:
Pros: requires no out-side configuration.
Cons: password is stored in plaintext.
Tento poslední způsob využívá vestavěnou proceduru ve specifikaci URL: tam lze vložit jméno uživatele a heslo přímo. Skladba URL je tato:
scheme://username:password@domain:port/path
takže, když provedete
hg clone https://alice:<secret>@bitbucket.org/aragost/private
použije Mercurial při přihlašování do Bitbucket automaticky alice jako jméno uživatele a <secret> jako heslo. Po úspěšném klonu je celé URL uloženo jako implicitní cesta v souboru .hg/hgrc jako normálně. Protože jsou heslo a jméno uživatele uloženy v URL, provedou se budoucí invokace hg pull a hg push automaticky bez promptů.
Pracujete-li často s repozitáři u téhož hostitele, může být únavným neustále opakovat:
hg clone https://hg.my-long-servername.com/repos/
Mercurial má standardní extenzi, která vám pomůže zkrátit dlouhou adresu URL. Povolíte extenzi schemes a do svého konfiguračního souboru můžete přidat následující:
[schemes] bb = https://bitbucket.org/
To vám dovolí psát:
hg clone bb://aragost/private
místo delšího:
hg clone https://bitbucket.org/aragost/private
Po povolení extenze si přečtěte bližší informaci v nápovědě hg help schemes.
Extenzi “schemes” můžete použít také pro URL při SSH, ale OpenSSH nabízí vlastní způsob zkracování adres. Vložte tyto řádky do souboru ~/.ssh/config (v případě potřeby jej vytvořte):
Host bb Compression yes HostName bitbucket.org User hg
To vám dovolí psát:
hg clone ssh://bb/aragost/private
místo:
hg clone ssh://hg@bitbucket.org/aragost/private
Všimněte si, že tato konfigurace dokonce dosadí vaše uživatelské jméno. Na to se snadno zapomene při používání SSH s Bitbucket. Využili jsme také příležitosti povolit kompresi pro tunel SSH, což celkově zlepšuje výkon.
Používáte-li Putty ve Windows (instalační paket je součástí instalace TortoiseHg), můžete učinit totéž konfigurací a uložením připojení. Uložíte-li konfiguraci pod jménem bb, potom můžete v Mercurialu začít používat způsob připojení ssh://bb/.
Jděte na https://bitbucket.org/ a otevřte si tam svůj účet.
Vytvořte privátní repozitář nazvaný test a naklonujte si jej do svého počítače.
Přidejte a komitujte soubor do repozitáře a pošlete jej zpět do Bitbucket.
Vytvořte ve svém počítači klon složky https://bitbucket.org/aragost/hello/
Vytvořte v Bitbucket nový repozitář nazvaný hello a pošlete (push) klon ‘hello’ ze svého počítače do Bitbucket.
Všimněte si, že lze poslat changesety do prázdného repozitáře. Je to proto, že můžete rozšířit hg clone na hg intit a na hg pull (až na to, že nedostanete hardlinky jak popsáno výše).
Co se stane, když se pokusíte poslat (push) z vašeho klonu hello do vašeho klonu test na Bitbucket? Jak Mercurial pozná, že jsou repozitáře spřízněny?