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

.. module:: tour
	:synopsis: A Gentle Introduction to Using TortoiseHg on Windows
	
	
Jak už bylo řečeno, TortoiseHg je extenze rozhranní Průzkumníka Windows a řada dalších grafických aplikací, které slouží jako uživatelsky příznivé prostředí pro rozptýlený systém kontroly verzí (DVCS) Mercurialu. Všechny nástroje TortoiseHg jsou přístupné přes kontextové menu Průzkumníka nebo pomocí aplikace příkazového řádku, nazvané :command:`hgtk`. Příkazy Mercurialu jsou také dostupné ze standardní aplikace příkazového řádku :command:`hg`.


Konfigurace programu
======================

Nejprve se musíme do programu TortoiseHg řádně zapsat. Uděláme to tak,
že upravíme jeho globální (uživatelské) nastavení. Pravým klepnutím kdekoli na volné ploše obrazovky otevřeme kontextové menu a vybereme :menuselection:`TortoiseHg -> Globální nastavení`

.. figure:: figures/cmenu-global-settings.jpg
	:alt: Desktop Context Menu

	Přístup ke globálnímu nastavení z plochy monitoru

Otevře se okno pro Globální nastavení uživatele. Používáme-li příkazový řádek, otevřeme toto okno příkazem :command:`hgtk userconfig`.

.. figure:: figures/settings.png
	:alt: Settings Dialog
	
	Konfigurace uživatele
	
Nejprve vybereme záložku :guilabel:`Commit` a zadáme jméno do textového pole :guilabel:`Jméno uživatele`.

.. note::
	Opomeneme-li zadat své jméno, zeptá se nás na něj program při 
	nejbližším použití příkazu *commit*; bude to poprvé, kdy je
	jméno požadováno.

.. note::
	Pro formátování uživatelského jména není pevné pravidlo ale obvykle se používá následující formát::
	
		Celé Jméno <email>
		
	například ::
	
		Donald Duck <donaldduck@example.net>
	
	Emailová adresa je odtržena při prohlížení historie změn a vestavěný webový server zakryje emailovou adresu
	v rámci prevence proti spamu.
	
Dále vybereme záložku :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áš vybraný slučovací nástroj také pro vizuální zobrazení diffů, necháme položku :guilabel:`Nástroj Visual Diff` neurčenu. Jinak si v rozvinovacím seznamu vybereme z nabízených nástrojů. 

Pokud nám v rozvinovacích seznamech není nabídnuta žádná volba, musíme nainstalovat slučovací 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 contrib/mergetools.ini do cesty HGRC. Možný způsob je připojit jej ze souboru ~/.hgrc.
	
Neostýchejme se v otevřeném okně konfigurovat i další položky globálního nastavení. Tato nastavení budeme moci později přepsat v konfiguraci repozitáře.

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

.. note::
	Většina nástrojů TortoiseHg vyžadují nové spuštění aplikace aby se projevily změny provedené v konfiguračním okně.

První seznámení
===============

Mercurial podporuje mnoho různých `modelů spolupráce <http://hgbook.red-bean.com/read/collaborating-with-other-people.html>`_. Tato kapitola popisuje pouze jeden z nich: model s centrálním repozitářem. Model s centrálním repozitářem je nejvíce známý těm, kteří přecházejí z jiných revizních systémů a je tedy nejvhodnější začít právě s ním.

Potřebujeme tedy vytvořit centrální repozitář. Bylo by možné přeměnit `nemercuriálový repozitář <http://mercurial.selenic.com/wiki/RepositoryConversion>`_ v repozitář Mercurialu ale v našem příkladu začneme úplně od začátku. 


Založení nového repozitáře
==========================

Nový repozitář na svém počítači vytvoříme buď výběrem :guilabel:`Vytvořit repozitář` z kontextového menu, nebo příkazem :command:`hgtk init` z příkazového řádku.  V kořenovém adresáři našeho projektu to stačí provést pouze jednou.

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

Dialogové okno pro vytvoření repozitáře

Je dobré ponechat volbu :guilabel:`Přidat specifické soubory (.hgignore, ...)`
zatrženou a nezatrhávat :guilabel:`Učinit repo kompatibilní s Mercurial 1.0`
pokud k tomu nemáme pádný důvod.

Po stisku tlačítka :guilabel:`Vytvořit`, vytvoří Mercurial v našem projektovém adresáři složku :file:`.hg`. Zde si program ukládá všechny  informace o jednotlivých verzích. Této složce se říká *repozitář*, zatímco adresář, který tuto složku obsahuje, je označován jako *pracovní adresář*.
Se složkou :file:`.hg` nikdy přímo nepracujeme. Při zadávání příkazů se případně odkazujeme na pracovní adresář.

Mezi pracovním adresářem a repozitářem existuje tajemná symbióza. Jak později poznáme, mění se obsah pracovního adresáře podle aktuálně nastavené revize.

Pojem pracovní adresář je tedy poněkud nejednoznačný. Je to jednak lokální adresář, do něhož jsme se přesunuli, jednak adresář, který souvisí s aktuálně nastavenou revizí.

Pokud to bude možné, bude v dalším textu první souvislost označována jako *adresář projektu* a *pracovní adresář* bude důsledně chápán jako odraz aktuální revize.


.. warning::
	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ů
=================

Mezi pracovním adresářem a repozitářem si představme přechodný prostor, do něhož se ukládají změny v pracovním adresáři před tím, než jsou předány k zápisu do repozitáře příkazem *commit*. Říkejme tomuto prostoru třeba *brašna*. Obdobný prostor v systému Git se nazývá *výstav*. 

Nyní je třeba říci aplikaci Mercurial, které soubory v pracovním adresáři (předpokládejme, že tam nějaké máme) mají být sledovány a které ignorovány. 
Lze to provést více způsoby - přidáme soubory do brašny dále uvedeným postupem ad 1 a 2:

1. V otevřeném adresáři otevřeme pravým klikem kontextovou nabídku
   a vybereme :menuselection:`TortoiseHg -> Přidat soubory...` (případně z 
   příkazové řádky příkazem :command:`hgtk add`). Objeví se
   dialogové okno, kde označíme soubory, které chceme do sledování přidat
   a potvrdíme volbu tlačítkem :guilabel:`Přidat`.
    
2. Nebo tamtéž volbou :menuselection:`TortoiseHg -> Status souboru`  
   (případně příkazem :command:`hgtk status` z příkazového řádku) 
   otevřeme dialogové okno, kde vybereme přidávané 
   soubory a potvrdíme křížkem :guilabel:`Přidat`. 
   V tomto okně lze také aktivovat zařazení nepřidávaného souboru do filtru
   tak, že pravým klikem ve zvýrazněném pruhu dosud nepřidaného souboru otevřeme další nabídku, kde 
   vybereme volbu :guilabel:`Ignorovat`, která
   otevře dialogové okno *Ignorované soubory - ...*
   
3. Nebo naplníme brašnu přímo v nástroji :menuselection:`THg --> Commit...`. 
   
4. Okno *Ignorované soubory - ...*, otevřeme také volbou :menuselection:`TortoiseHg -> 
   Ignorované soubory...` 
   případně příkazem :command:`hgtk hgignore`. Vybereme soubor ze seznamu nebo
   vepíšeme do textového okna filtru *Glob* či *Regexp* (Regular expression)  a potom
   potvrdíme tlačítkem :guilabel:`Přidat`. Změny zadané v těchto filtrech
   se projeví okamžitě.
   
.. note::
	Soubor :file:`.hgignore` se vytvoří automaticky při první volbě ignorovaného souboru a je v běžných případech zahrnován do sledování repozitářem.

.. note::
	Je dobrým zvykem nemít mnoho *neznámých* souborů ve svém pracovním adresáři.


Commit
======

Změny provedené v pracovních souborech předáme z brašny do svého repozitáře příkazem :guilabel:`commit` (předat či potvrdit). V otevřeném pracovním adresáři otevřeme nabídku :guilabel:`TortoiseHg --> Commit...` ,
nebo zadáme příkaz :command:`hgtk commit`.  
Napíšeme průvodní komentář, vybereme soubory, které chceme předat  a stiskneme 
:guilabel:`Commit`. Pokud si před uzavřením okna *Commit* uvědomíme, že jsme commit vlastně nechtěli,
můžeme jej ještě zrušit tlačítkem :guilabel:`Zpět`.  


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

	Okno akce Commit

Klonování repozitáře
====================

Nyní své výtvory již můžeme sdílet s ostatními. Zkopírujeme svůj repozitář
někam, kam mají přístup všichni členové naší skupiny. Tomuto úkonu se říká
*klonování repozitáře*. Provedeme jej nástrojem :menuselection:`TortoiseHg -> Klonovat...`, nebo příkazem
:command:`hgtk clone` z příkazového řádku.  Potom zadáme cestu k místu určení.

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

	Okno akce Clone

Vytváříme-li klonováním *centrální repozitář*, potom nemusíme kopírovat
celý obsah pracovního adresáře. Zatržením volby :menuselection:`Neaktualizovat nový pracovní adresář` zajistíme kopírování pouze složky :file:`.hg`, která obsahuje úplnou historii revizí projektu.

Dalším klonováním tohoto klonu lze získat opět kompletní pracovní adresář (!), pokud tentokrát ponecháme výše popsanou volbu nezatrženou.

Doplňující poznámky
===================

V dalším textu této kapitoly se jestě setkáme s příkazy :menuselection:`Aktualizovat`, :menuselection:`Pull` (stáhnout) a :menuselection:`Push` (vystrčit). Poslední dva příkazy nalezneme v okně :menuselection:`ToroiseHg -> Synchronizovat`, případně je lze
zadat příkazem :command:`hgtk pull` respektive :command:`hgtk push`. Změny si lze před :menuselection:`Pull` a :menuselection:`Push` prohlédnout příkazem :guilabel:`Příchozí` a :guilabel:`Odchozí`.

Příkaz :menuselection:`Pull` přetáhne změny z repozitáře do repozitáře,
ale aby se tyto změny promítly do našich pracovních souborů, 
musíme provést akci :guilabel:`Aktualizovat`. Tento příkaz sám provede i sloučení
rozdílných verzí, pokud se změna nachází pouze v jedné z nich. Pokud byly
měněné obě verze, musíme provést jejich sloučení příkazem :command:`hg merge`. Provedený příkaz :menuselection:`pull` nás na to sám upozorní (run 'hg heads' to see heads, 'hg merge' to merge).

Příkazem :guilabel:`Push` vyšleme sloučené verze zpět do centrálního
repozitáře. Patří k dobrému vychování neukládat v centrálním repozitáři
rozdílné verze stejného souboru.

Práce s repozitáři
==================

Konkretní použití jednotlivých příkazů si názorně ukážeme na následujícím schematickém příkladu - viz obrázek. Příkazy budeme zadávat z příkazového řádku konzoly cmd.exe. Představme si situaci, že náš počítač používají dvě osoby, Petr a Pavel. Petr založí adresář "bim" a v něm vytvoří první repozitář příkazem :command:`hgtk init`:: 

	c:\bim> hgtk init  --> Otevře se okno "Vytvořit nový repozitář"
	
	Destinace: c:\bim
	x Přidat specifické soubory (.hgignore, ...)
	  Učinit repo ...
	Vytvořit

V otevřené složce **bim** vytvoří Petr nový textový soubor "bob.txt" s textem "Nazdar". Svoji práci potom předá do repozitáře::

	c:\bim> echo Nazdar > bob.txt
	
	c:\bim> hgtk commit  --> Otevře se okno "bim - commit"
	
	Do textového pole Petr zapíše průvodní text první revize (neboli changesetu): "bim mess 0"
	Commit
	
.. figure:: figures/repos.png
	:alt: Coordination scheme
	
Koloběh příkazů mezi repozitáři


**V dalším textu si vysvětlíme jednotlivé aktivity 1 - 9:**

1. Petr vytvoří klonováním centrální repozitář :guilabel:`bam`. Tento repozitář nemusí 
obsahovat pracovní soubory::
	c:\bim> hgtk clone  --> Otevře se okno "Klonovat repozitář"
	
	Cesta ke zdroji: c:\bim
	Cesta k destinaci: c:\bam  # vytvoří i adresář
	x Neaktualizovat novou pracovní složku
	Klonovat
2. Máme pracovní adresář "bam" s repozitářem, který budeme považovat za
centrální. Obsahuje pouze složku :guilabel:`.hg`. Pavel si založí adresář
:guilabel:`bum` a do něho si pořídí kopii centrálního repozitáře včetně pracovních
souborů::
	c:\bum> hgtk clone  --> Otevře se okno "Klonovat repozitář"
	
	Cesta ke zdroji: c:\bam
	Cesta k destinaci: c:\bum
	# "Neaktualizovat novou pracovní složku" se tentokrát nezatrhne
	Klonovat
3. Máme tři pracovní adresáře, Petr i Pavel mají totožné pracovní soubory.
Petr do svého souboru připíše "bim bim", Pavel "bum bum". Své nyní již rozdílné
změny potvrdí do svých repozitářů::
	c:\b~m> hgtk commit  --> Otevře se okno "b~m - commit"
	
	zapíše se průvodní text, např. "bim mess 1", respektive "bum mess 1"
	Commit
4. Musíme si uvědomit, že ve skutečnosti nevíme, co se děje v centrálním
repozitáři. Může již obsahovat změny pracovních souborů. Dejme tomu Petr
tedy provede akci::
	c:\bim> hgtk pull  -->  Otevře se okno "bim - synchronizovat"
	
	Do textového pole pro *Repo:* zadáme adresu centrálního repozitáře  (c:\bam)
	Příkazem "Příchozí" si zobrazíme případné změny, které mohou být převzaty
	z centrálního repozitáře
	Příkazem "Pull" převezmeme případné změny do svého pracovního adresáře. 
5. V našem schematu předpokládáme, že žádné změny nejsou, takže můžeme
bez dalšího "vystrčit" naše změny zpět do centrálního repozitáře::
	c:\bim> hgtk push  --> Otevře se totéž okno
	
	Pomocí tlačítka "Repo:" zadáme adresu centrálního repozitáře
	Můžeme se příkazem "Odchozí" podívat co může odejít
	Příkazem "Push" změny pošleme
6. Pavel si aktuální stav repozitáře stáhne již popsaným způsobem
:: 
	c:\bum> hgtk pull  --> Otevře se okno "bum - synchronizovat"
	
	Zkontroluje adresu centrálního repozitáře
	Pull
7. Pavlova situace je teď odlišná od Petrovy. V jeho pracovním adresáři se nacházejí dvě různé verze téhož souboru. Již při provádění příkazu "pull" byl upozorněn, že má provést příkaz "merge"
::
	c:\bum>hgtk merge  --> Otevře se okno "KDiff3"
	
	Postupným výběrem dvou písmen z A, B, C vytvoří sloučení a uloží.
8. Provedené změny musí předat repozitáři
:: 
	c:\bum>hgtk commit --> Otevře se okno "bum - commit"
	
	Zapíše průvodní text, například "Merge one"
	Commit
9. Sloučenou verzi odešle Pavel zpět do centrálního repozitáře
::
	c:\bum> hgtk push

Jednotlivé příkazy budou v dalších kapitolách probrány ještě jednou a podrobněji.

.. vim: noet ts=4