******************************
A quick tour for the impatient
******************************

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

Mercurial supports many different
`collaboration models <http://hgbook.red-bean.com/read/collaborating-with-other-people.html>`_.
This chapter describes just one of those models: a single central repository.
The central repository model does not scale as well as other models, but
it is the most familiar to those coming from other revision tools and
thus is the most common approach people start with.

To get started, suppose you volunteer to create the central repository.
There are ways to `convert <http://mercurial.selenic.com/wiki/RepositoryConversion>`_
non-Mercurial repositories into Mercurial repositories, but this example
assumes you are starting from scratch.

This tutorial assumes you already have TortoiseHg properly installed,
and you have your project folder open in your file browser.


Configuring TortoiseHg
======================

First you need to make sure that you are correctly identified in
TortoiseHg.  You do this by adjusting the global settings of TortoiseHg.
Right click in your source folder and select
:menuselection:`TortoiseHg --> Global Settings`

.. figure:: figures/cmenu-nofiles.jpg
	:alt: Context Menu

	Context menu with no files selected

You must then select the :guilabel:`Commit` tab and enter a name in the
:guilabel:`Username` field.

.. note::
	If you forget to configure your username TortoiseHg will ask you to
	enter one when you *commit*, the only time the name is actually
	required.

.. note::
	There are no hard rules on how to format your user name, the field
	is free form, but the following convention is commonly used::
	
		FullName <email>
		
	for example ::
	
		Donald Duck <donaldduck@example.net>
	
	The email address is stripped when viewing history in the changelog
	viewer, and the built-in web server obfuscates email addresses to
	prevent SPAM.

If you are not using one of our Windows installers, you will also have
to configure a visual diff tool.  Type :command:`hgtk userconfig` and on
the TortoiseHg tab you will find :guilabel:`Visual Diff Command`.  If
there are no options in the drop-down list, you must enable and
configure Mercurial's ExtDiff extension and then restart the userconfig
application.


Initialize the repository
=========================

Create the initial repository on your local machine by using the
:guilabel:`Create Repository Here` shell menu option, or in a command
shell within the folder, type :command:`hgtk init`.  You only need to do
this in once in the root folder of your project.

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

	Repository Init Dialog

We suggest you keep :guilabel:`Add special files (.hgignore, ...)`
checked, and do not check
:guilabel:`Make repo compatible with Mercurial 1.0`
unless you have a strong reason to do so.

After pressing :guilabel:`Create`, Mercurial creates a subdirectory in
your project folder named :file:`.hg`. This is where Mercurial keeps all
its version data.  It is called the *repository* or *store*, while the
directory containing the source files is called the *working directory*.
You never need to specify the :file:`.hg` directory when running
commands, you only need to specify the working directory root.  It is
mentioned here just so you better understand how Mercurial works.

.. warning::
	It is dangerous to manually edit the files in :file:`.hg` directory,
	repository corruption can occur.  :file:`.hg/hgrc` is perhaps the
	only exception to this rule.

Add files
=========

Now it's time to tell Mercurial which files must be tracked and which
files must be ignored. There are a lot of way to do this:

1. To add files, select them in explorer and then right click and select
   :menuselection:`TortoiseHg --> Add Files...` in the context menu. A
   dialog will open for you to double check the selected files and
   accept the add operation.
 
2. Or open the status tool (:menuselection:`TortoiseHg --> View File Status`
   or :command:`hgtk status` from the command line). Check the files you
   want to add and then press the :guilabel:`Add` button. From the
   status tool you can launch the ignore filter tool from the context
   menu of a unknown file (the menu option is named :guilabel:`ignore`)
   
3. Or skip adding new files as a separate step and have the commit tool
   add them implicitly.  The commit tool is very similar to the status
   tool and allows you to do all of the same tasks. In this tool you
   can add and commit an untracked file by just checking the file and
   pressing :guilabel:`Commit`.
   
4. To ignore files, open the ignore filter dialog:
   :menuselection:`TortoiseHg --> Edit Ignore Filter` or from command
   line :command:`hgtk hgignore`. Choose a file from the list or
   manually type in a *Glob* or *Regular expression* filter and then
   press :guilabel:`Add`. Changes to the ignore filter take effect
   immediately.
   
.. note::
	The :file:`.hgignore` file, contained in the working directory root,
	is typically tracked (checked in).

.. note::
	It is good practice to not have many *unknown* files in your working
	directory, as it makes it too easy to forget to add vital new files.
	It is recommended that you keep your :file:`.hgignore` file up to
	date.


Commit
======
   
Commit your local repository by right-clicking anywhere in the folder,
or on the folder itself, and then selecting :guilabel:`HG Commit ...`,
or from command line type :command:`hgtk commit`.  Write a commit
message, select the files you wish to commit, then press
:guilabel:`Commit`. If, after the commit, you realize that something was
wrong with the message or the selected files, you can cancel the last
commit using the :guilabel:`Undo` button.  Your previous commit message
will be in the message history drop-down, so you do not have to type it
in again from scratch.

.. note::
	You lose the ability to easily undo the last commit when you close
	the commit tool.

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

	Commit Tool

Share the repository
====================

Now you are ready to share your work. You do this by making a copy of
your repository in a public location that everyone in your group can
read. Mercurial calls this copy operation *cloning your repository*. To
clone your repository to a shared drive, open the clone tool
:menuselection:`TortoiseHg --> Clone a Repository`, or
:command:`hgtk clone` from command line.  Then enter the destination
path.

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

	Clone Dialog

When you create a clone for the purposes of generating a *central
repository* there is no reason for that clone to have a working
directory. Checking
:guilabel:`do not update the new working directory` will prevent
Mercurial from checking out a working copy of the repository in the
central repository clone.  It will only have the :file:`.hg` directory,
which stores the entire revision history of the project.

Other team members can clone from this clone with or without a checked
out working directory.


Fetching from the group repository
==================================

You want to start collaborating with your team.  They tell you something
like *fetch the repository from x*.  What does that mean? It means that
you want to make a copy of the repository located at x on your local
machine.  Mercurial calls this cloning and TortiseHg has a dialog
for it. Right click in the directory where you want your copy and select
:menuselection:`TortoiseHg --> Clone a Repository`, or
:command:`hgtk clone` from command line.

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

	Clone Dialog

This time you do want to update the working directory because you want
to work on the project, uncheck
:guilabel:`do not update the new working directory` so Mercurial updates
the working directory with the *tip* revision in your new clone.


Working with your repository
============================

Suppose you've introduced some changes. It is easy to see that there are
a couple of directories with changes pending.  You can traverse the
directories to find specific changes and commit them from Explorer. A
quicker way is to use the commit tool:

.. {{images/image001.png}}
.. figure:: figures/overlayicons.png
	:alt: Overlay Icons 

	Overlay Icons on Vista

The commit tool gives you a way to see differences or you can use your
visual difference tool (kdiff). Mercurial allows you to commit many
changes before you decide to synchronize (share changes) with the group
repository.


When you're ready to publish your changes, you

1. Commit your changes to your local repository (see above).
2. Pull changes from the group repository into your repository,
   :menuselection:`TortoiseHg --> Repository Browser` or
   :command:`hgtk log`, choose the path to the group repository
   in the syncbar and then :guilabel:`Pull`.
3. If some changesets were pulled, merge those changes with your local
   changes and then commit the merge into your local repository. From
   the changelog viewer (:menuselection:`TortoiseHg --> Repository Browser`
   or :command:`hgtk log`) open the context menu over the changeset
   which you want to merge and select :guilabel:`merge with`.
   Finally, in the merge dialog, press :guilabel:`Merge` and then
   :guilabel:`Commit`.
4. Ensure your merged work still builds and passes your extensive test suite.
5. Push your changes to the group repository,
   :menuselection:`TortoiseHg --> Repository Browser` or :command:`hgtk log`,
   choose the path to group repository and then :guilabel:`Push`.

Which may sound complicated, but most of the time it is just pushing the
buttons in the commit and changelog tools.

.. note::
	Merges can be safely restarted if necessary.

Mercurial makes collaboration easy, fast, and productive.
Learn more at Mercurial's `wiki <http://mercurial.selenic.com/wiki/>`_.

.. vim: noet ts=4
