.. _hg_primer:

================
hg in a Nutshell
================

Hg is the chemical symbol for mercury.
hg is the unix command that runs `Mercurial` the revision control system.

As a user of Theano, the commands you need to know are:

``hg clone 'ssh://projects@pylearn.org/hg/Theano'``
    Download the freshest version of the code from the remote respository.

``hg pull -u``
    Update your files to the freshest versions from the remote repository.

As a developer of Theano, you may want to change the local code, and merge them
with the central version.  This requires a bit more understanding of what's
going on.  Working with hg means you have three logically seperate kinds of images of the
codebase: local files, local database, remote database(s).

Typically, your sequence of hg commands should look like this:

1. ``hg pull -u [remote address]``
    (Copy from remote db -> local db -> local files)

#. ``<change local files>``
    This will create differences between the local files and the local db.
    Prefer using ``hg rm`` and ``hg mv`` to their unix counterparts.  

#. ``hg st``
    (Print out differences between local files and local db)

#. ``hg commit -m 'message about what you did' <files to which message applies>``
    (Update the local db to match the files listed.)

#. ``hg pull -u``
    (Download the remote db to the local db, and ``-u`` updates files too.)

#. ``[hg merge]``
    (Downloading the remote db may have created a fork in the
    local db.  This command will try to merge any such fork, and it might bring up
    an editor to merge some stuff manually. This step affects the local files, but
    not the local db.)

#. ``[hg commit -m 'merge']``
    (If you changed your files during the merge
    operation, then you have to commit those changes, as usual.)

#. ``hg push [remote address]`` 
    (Update the remote db to match the local db)

Note that *branching* in mercurial is as easy as ``cp <repo> <new name>`` in a
unix shell.  If you want to make ``<repo>`` the default push location of your
new branch that do ``hg clone <repo> <new name>`` instead.

Failure to do these commands in the proper order can get you into a tricky
state, where you can't push because it would create a branch, and you can't pull
or update because it says it's done, and you can't commit because it says
nothing to commit, and you can't merge, and oh the pain.... so be careful!  
If this happens to you, consider just re-cloning the repo and merging in your
old changes by hand.

For more info, check out the `homepage <http://www.selenic.com/mercurial/wiki/>`_ and `hg book <http://hgbook.red-bean.com/hgbook.html>`_.

Tip: Commit before pull
------------------------

"This is the general rule of thumb when using Mercurial: finish your work
and commit it before you start pulling in stuff from the outside world."
-Martin Geisler
(http://www.selenic.com/pipermail/mercurial/2008-April/018817.html)

Tip: Graph logs
---------------

Update your .hgrc::

    [ui]
    username = Foo Bar <barfoo@iro.umontreal.ca>

    [extensions]
    hgext.graphlog =

Now try::

    hg glog

Troubleshooting
---------------

If you get message: "abort: push
creates new remote heads!", read `this thread
<http://www.selenic.com/pipermail/mercurial/2008-April/018804.html>`_
to understand.
