****************************
Rychlá cesta pro netrpělivé
****************************

.. module:: tour
    :synopsis: A Gentle Introduction to Using TortoiseHg on Windows

Jak už bylo řečeno, TortoiseHg je sada grafických aplikací, které spolu s Průzkumníkem Windows slouží jako uživatelsky přívětivé rozhranní pro DVCS Mercurialu (distributed version control system - necentralizovaný systém správy verzí).

Všechny nástroje TortoiseHg jsou přístupné ze třech míst:

1. Z aplikace **Verpánek**

   Verpánek (Workbench) spustíme z menu Start nebo z kontextového menu aktivovaného poklepem pravé klávesy myši s kurzorem kdekoli v ploše monitoru.

   .. figure:: figures/desktop-workbench.png
    :alt: Desktop Context Menu

    Spuštění Verpánku z plochy monitoru


2. Z kontextového menu **Explorer**

   Na vybrané složce či souboru v Průzkumníku provedeme pravý poklep a vybereme položku z kontextového menu.

3. Příkazem **thg** z příkazového řádku

   V konzoli cmd.exe či v jiném terminálu zadáme příkaz  :command:`thg <command> [opce]`.

Příkazy Mercurialu jsou dostupné také z příkazového řádku příkazem :command:`hg <command>`.

.. note:: Při zadávání příkazu z příkazového řádku se předpokládá, že repozitórium je aktuálním adresářem příkazové konzoly.


Nastavení programu
==================

Nejprve se musíme do programu TortoiseHg řádně zapsat. Uděláme to tak, že otevřeme dialog pro globální nastavení.

Verpánek: :menuselection: `File > Settings`

Průzkumník: :menuselection: `TortoiseHg > Globální nastavení`

Příkazem: **thg userconfig**

Tím si otevřeme dialogové okno Nastavení TortoiseHg pro úpravu globální konfigurace platné pro všechny repozitáře.

.. figure:: figures/settings.png
    :alt: Settings Dialog

    Okno TortoiseHg Settings

Nejprve vybereme kartu :guilabel:`Commit` a zadáme jméno v poli :guilabel:`Jméno uživatele`.

.. note::
    Pokud nezadáme uživatelské jméno nyní, budeme na něj tázáni   později, až poprvé použijeme příkaz ``commit``.

.. note::
	Pro formátování uživatelského jména není pevné pravidlo ale obvykle se používá následující forma::

		Celé Jméno <email>

	například ::

		Donald Duck <donaldduck@example.net>

	Emailová adresa je při prohlížení změn odtržena a vestavěný webový server emailovou adresu zakryje v rámci prevence proti spamu.

Dále vybereme katru :guilabel:`TortoiseHg` a v ní :guilabel:`Nástroj pro sloučení`. V rozvinovacím seznamu nalezneme všechny slučovací nástroje nalezené v programovém vybavení počítače (kdiff3 je poskytnut instalátorem pro Windows) a řadu interních způsobů sloučení. Vybereme si oblíbený nástroj pro slučování.

Pokud chceme, aby TortoiseHg používal námi vybraný slučovací nástroj také pro zobrazení diffů, necháme položku :guilabel:`Nástroj pro sloučení` neurčenu. Jinak si v rozvinovacím seznamu vybereme z nabízených nástrojů.

Pokud nám v uvedených položkách není nabídnuta žádná volba, musíme instalovat nástroj, který je podporován v mergetools.rc nebo si nakonfigurovat nástroj vlastní.

.. note::
	Při instalaci TortoiseHg ze zdroje, je nutné nějakým způsobem přidat soubor :kbd:`contrib/mergetools.ini` do cesty HGRC. Možný způsob je připojit jej ze souboru :kbd:`~/.hgrc`.

Neostýchejte se konfigurovat i další položky globálního nastavení. Budeme je moci později přepsat v lokální konfiguraci repozitáře.

Nastavené změny potvrdíme a okno zavřeme tlačítkem :command:`OK`.

.. note::
	Většina změn nastavení TortoiseHg se projeví okamžitě ale povolení nebo zakázání extenzí obvykle vyžadují restart.

Status souboru
==============

Soubory, obsluhované Mercurialem, mají různý vztah k zapisované historii. Tento vztah je vyjádřen jako *status* souboru příslušným označením:

* A (added)     přidaný do komitu - příkazem *hg add*
* M (modified)  změněný
* I (ignored)   ignorovaný, uvedený v seznamu *.hgignore*
* ! (missing)   postrádaný, většinou ručně smazaný
* R (removed)   odebraný - příkazem *hg remove*
* ? (unknown)   neznámý, přidaný do repozitória ručně
* C (clean)     čistý, beze změn



Vytvoření repozitória a repozitáře
==================================

Jak bylo již uvedeno v Předmluvě (odst. 1.7), budeme z didaktických důvodů rozlišovat mezi repozitářem a repozitóriem. Za repozitář budeme považovat
složku .hg, za repozitórium její kořenový adresář.

Repozitórium můžeme vytvořit z existující složky, kde umístíme repozitář, nebo vytvoříme složku repozitória i repozitáře současně.

Můžeme si vybrat jeden ze tří způsobů:

Verpánek: :menuselection:`File > Nový repozitář...`

Průzkumník: :menuselection:`TortoiseHg > Vytvořit repozitář` z kontextového menu

Příkaz: :command:`thg init`



.. figure:: figures/init.png
	:alt: Repository Init dialog

Dialogové okno pro vytvoření repozitáře či repozitória

Je dobré ponechat volbu :guilabel:`Vytvořit specifické soubory (.hgignore, ...)`
zatrženou a nezatrhávat :guilabel:`Vytvořit repozitář kompatibilní s Mercurialem < 1.7` pokud k tomu nemáme pádný důvod.

Po stisku tlačítka :guilabel:`Vytvořit`, vytvoří Mercurial v našem repozitóriu složku repozitáře :file:`.hg`. Zde si program ukládá všechna  verzovaná data.
Se složkou :file:`.hg` nikdy přímo nepracujeme. Při zadávání příkazů se odkazujeme na repozitórium.

Nové repozitórium se také přidá do Seznamu repozitářů , pokud tuto operaci provedeme z Verpánku.
Nezařazená repozitória můžete přidat do Seznamu repozitářů výběrem :menuselection:`File > Otevřít repozitář...` nebo je můžete přetáhnout z Průzkumníka.

.. note::
    Mezi právě aktuálními revizemi a repozitóriem existuje tajemná symbióza. Jak později poznáme, mění se obsah repozitória podle aktuálně nastavené revize. Ponecháme-li aktuální starší revizi, můžeme případné nověji přidané soubory v Průzkumníku Windows (tedy v repozitóriu) nevidět!

.. warning::
	Ručně editovat soubory ve složce :file:`.hg` je nebezpečné, může dojít k poškození repozitáře. Jedinou výjimkou je konfigurační soubor :file:`.hg/hgrc`.

Přidávání souborů
=================

Nyní je třeba aplikaci Mercurial sdělit, které soubory mají být sledovány. Lze to provést více způsoby:

1. Verpánek: ikonou :menuselection:`Commit` otevřeme úkonovou kartu, pravým poklepem zvýrazníme vybraný soubor a z kontextového menu vybereme :menuselection:`Add` . To změní status souboru na 'A' a po zatržení nabídky barva názvu zezelená.

2. Explorer: vybereme :menuselection:`TortoiseHg > Přidat soubory...` v kontextovém menu vybraného souboru. Otevře se okno pro zadání výběru a potvrzení operace :menuselection:`add`. Stejným způsobem lze vybrat nabídku :menuselection:`TortoiseHg > Status souboru`. V otevřeném dialogovém okně můžeme vybrat zamýšlené soubory.

3. Příkazem: :command:`thg status`

4. Přidávání souborů v samostatném kroku můžeme přeskočit a přidat je implicitně v rámci příkazu :menuselection:`TortoiseHg > Commit...`. Otevře se podobné dialogové okno jako u volby :menuselection:`Status souboru`. Vybereme zařazovaný, dosud nesledovaný soubor a volbu potvrdíme tlačítkem :guilabel:`Commit`.



Ignorování souborů
==================

Ve svých repozitóriích můžeme mít z různých důvodů soubory, jež nechceme sledovat. Tyto soubory lze označit jako ignorované a to rovněž několika způsoby.

1. Verpánek: aktivujte panel Commit, na zvýrazněném souboru vyvolejte kontextové menu a vyberte :menuselection:`Ignorovat...`.

2. Explorer: vyberte :menuselection:`TortoiseHg > Ignorované soubory`

3. Příkazem :command:`thg hgignore` otevřeme dialogové okno pro filtrování souborů.

Pro vybraný soubor určíte druh filtru (`Glob` nebo `Regexp`) a zadáte :command:`Přidat`. Změny filtru :guilabel:`ignore` se projeví okamžitě.

.. note::
    Soubor :file:`.hgignore`, obsažený repozitóriu, je normálně sledován (checked in).

.. note::
    Je dobré, nemít v repozitóriu mnoho `neznámých` souborů,   protože se potom snadno zapomene přidat důležité nové soubory. Doporučuje se udržovat soubor :file:`.hgignore` v aktuálním stavu.


Commit
======

Předání změn do repozitáře provedete následujícím způsobem:

Verpánek: Poklepem na pracovní adresář se otevře panel pro předání změn (commit), případně tento panel můžete aktivovat výběrem ikony s `fajfkou`.

Explorer: Pravým poklepem kdekoliv ve složce otevřete kontextové menu a vyberete dialogové okno :menuselection:`TortoiseHg > Commit...`.

Příkaz:  :command:`thg commit`

Napíšete předávací zprávu, vyberete soubory, které chcete předat a přikážete :guilabel:`Commit`. Předchozí předávací zpráva bude uvedena v roletkovém seznamu; v případě potřeby ji lze s úpravou použít.


.. figure:: figures/commit.png
	:alt: Commit dialog

	Zadávací okno TortoiseHg > Commit


Sdílení repozitářů
==================

Mercurial podporuje mnoho různých `modelů spolupráce <https://tortoisehg.bitbucket.io/hgbook/1.7/collaborating-with-other-people.html>`_. Tento odstavec popisuje pouze jeden z nich: model s centrálním repozitářem.

Na místě, kam mají přístup všichni členové skupiny se vytvoří centrální repozitář, kam všichni posílají své změny, přičemž jeden člen kolektivu má za úkol na tento repozitář dohlížet.

Tento centrální repozitář může vzniknout jako nový repozitář nebo jako kopie (klon) již někde jinde vytvořeného repozitáře. *Klonování repozitáře* lze provést trojím způsobem:

Verpánek: Z menu vyberete :menuselection:`File > Klonovat repozitář...`

Explorer: Z kontextového menu vyberete :menuselection:`TortoiseHg > Klonovat...`

Příkaz: :command::`thg clone`.

Potom zadáte cestu k destinaci a zavelíte :command:`Klonovat`.

.. figure:: figures/clone.png
	:alt: Clone dialog

	Okno akce Clone

Vytváříte-li *centrální repozitář* klonováním, potom nemusíte kopírovat
celý obsah repozitória. Zatržením volby :guilabel:`Neaktualizovat nový pracovní adresář` zajistíte kopírování pouze složky :file:`.hg`, která obsahuje úplný přehled revizí projektu.

Další členové skupiny si tento centrální repozitář naklonují již s nezatrženou volbou :guilabel:`Neaktualizovat nový pracovní adresář`.
Tím si do svého lokálního repozitoria přenesou i pracovní soubory.

Klonováním vzniká příbuzenský vztah mezi repozitáři. Akce *pull* a *commit* lze provádět pouze mezi příbuznými repozitáři. Příbuzný repozitář na jiném počítači je repozitář vzdálený (remote).


Práce s repozitářem
===================

Předpokládejme, že jste provedl nějaké změny. Zda máte v (pomyslném) pracovním adresáři nepředané (nekomitované) změny zjistíte snadno:

**Verpánek**: V panelu úlohy Commit prohlédneme seznam souborů na levé straně.

Šifry **A** (přidaný - zelená) a **M** (upravený - modrá) označují soubory, které lze komitovat přímo. Soubory označené **?** (neznámý - fialková), **!** (postrádaný - červená) či **R** (odebraný - červená) nutno nejprve přidat či vrátit do sledování.

Spodní pole vpravo karty Commit vám zobrazí i změny v jednotlivých souborech nebo můžete použít svůj nástroj pro zobrazování rozdílů (kdiff3). V Mercurialu lze provést řadu komitů předtím, než se rozhodnete pro sdílení svých změn s repozitářem centrálním.

**Explorer**: Složky a soubory vašeho repozitória jsou označeny jednou z  překryvných ikon. Ty vám napoví, v jakém stavu se ten či onen soubor nebo složka nachází.

.. figure:: figures/overlayicons.png
	:alt: Overlay Icons

	Překryvné ikony

**Příkazový řádek**: Příkazem :command:`thg commit` vyvoláte dialogové okno.

Jste-li připraven zveřejnit své změny, provedete následující:

1. Předáte změny do svého lokálního repozitáře (provedete komit).
2. Aktivujete kartu pro synchronizaci, vyberete cestu k centrálnímu repozitáři a stisknete tlačítko :guilabel:`Pull`, čímž vydáte příkaz ke stažení možných změn z tohoto repozitáře.
3. Byly-li nějaké changesety staženy, provedete jejich případné sloučení s vašimi lokálními změnami a provedete jejich komit do repozitáře.

V přehledu changesetů zviditelníte ten, se kterým chcete sloučení provést, aktivujete kontextové menu a vyberete :guilabel:`Merge with local...`. V dialogovém okně pro sloučení stisknete :command:`Sloučit` (merge) a posléze :command:`Commit`.
4. Sloučenou práci prověříte svým testovacím postupem.
5. V kartě pro synchronizaci vyberete cestu k centrálnímu repozitáři a pošlete do něho své změny tlačítkem :command:`Push`.

.. note:: Sloučení lze bezpečně v případě potřeby opakovat.

Spolupráce prostřednictvím Mercurialu je snadná, rychlá a produktivní. Více o Mercurialu na jeho stránkách `wiki <https://www.mercurial-scm.org/wiki/CzechMercurial>`_.


.. vim: noet ts=4
