1 .. -*- coding: utf-8 -*-

     2 

     3 .. _MercurialPresentation:

     4 

     5 Introducing Mercurial

     6 =====================

     7 

     8 Introduction

     9 ````````````

    10 Mercurial_ manages a distributed repository containing revisions

    11 trees (each revision indicates the changes required to obtain the

    12 next, and so on). Locally, we have a repository containing revisions

    13 tree, and a working directory. It is possible

    14 to put in its working directory, one of the versions of its local repository,

    15 modify and then push it in its repository.

    16 It is also possible to get revisions from another repository or to export

    17 its own revisions from the local repository to another repository.

    18 

    19 .. _Mercurial: http://www.selenic.com/mercurial/

    20 

    21 In contrast to CVS/Subversion, we usually create a repository per

    22 project to manage.

    23 

    24 In a collaborative development, we usually create a central repository

    25 accessible to all developers of the project. These central repository is used

    26 as a reference. According to their needs, everyone can have a local repository,

    27 that they will have to synchronize with the central repository from time to time.

    28 

    29 

    30 Major commands

    31 ``````````````

    32 * Create a local repository::

    33 

    34      hg clone ssh://myhost//home/src/repo

    35 

    36 * See the contents of the local repository (graphical tool in Qt)::

    37 

    38      hgview

    39 

    40 * Add a sub-directory or file in the current directory::

    41 

    42      hg add subdir

    43 

    44 * Move to the working directory a specific revision (or last

    45   revision) from the local repository::

    46 

    47      hg update [identifier-revision]

    48      hg up [identifier-revision]

    49 

    50 * Get in its local repository, the tree of revisions contained in a

    51   remote repository (this does not change the local directory)::

    52 

    53      hg pull ssh://myhost//home/src/repo

    54      hg pull -u ssh://myhost//home/src/repo # equivalent to pull + update

    55 

    56 * See what are the heads of branches of the local repository if a `pull`

    57   returned a new branch::

    58 

    59      hg heads

    60 

    61 * Submit the working directory in the local repository (and create a new

    62   revision)::

    63 

    64      hg commit

    65      hg ci

    66 

    67 * Merge with the mother revision of local directory, another revision from

    68   the local respository (the new revision will be then two mothers

    69   revisions)::

    70 

    71      hg merge identifier-revision

    72 

    73 * Export to a remote repository, the tree of revisions in its content

    74   local respository (this does not change the local directory)::

    75 

    76      hg push ssh://myhost//home/src/repo

    77 

    78 * See what local revisions are not in another repository::

    79 

    80      hg outgoing ssh://myhost//home/src/repo

    81 

    82 * See what are the revisions of a repository not found locally::

    83 

    84      hg incoming ssh://myhost//home/src/repo

    85 

    86 * See what is the revision of the local repository which has been taken out

    87   from the working directory and amended::

    88 

    89      hg parent

    90 

    91 * See the differences between the working directory and the mother revision

    92   of the local repository, possibly to submit them in the local repository::

    93 

    94      hg diff

    95      hg commit-tool

    96      hg ct

    97 

    98 

    99 Best Practices

   100 ``````````````

   101 * Remember to `hg pull -u` regularly, and particularly before

   102    a `hg commit`.

   103 

   104 * Remember to `hg push` when your repository contains a version

   105   relatively stable of your changes.

   106 

   107 * If a `hg pull -u` created a new branch head:

   108 

   109    1. find its identifier with `hg head`

   110    2. merge with `hg merge`

   111    3. `hg ci`

   112    4. `hg push`

   113 

   114 Installation of the guestrepo extension

   115 ```````````````````````````````````````

   116 

   117 Set up the guestrepo extension by getting a copy of the sources

   118 from https://bitbucket.org/selinc/guestrepo and adding the following

   119 lines to your ``~/.hgrc``: ::

   120 

   121    [extensions]

   122    guestrepo=/path/to/guestrepo/guestrepo

   123 

   124 

   125 More information

   126 ````````````````

   127 

   128 For more information about Mercurial, please refer to the Mercurial project online documentation_.

   129 

   130 .. _documentation: http://www.selenic.com/mercurial/wiki/

   131