doc/book/en/annexes/mercurial.rst
branchtls-sprint
changeset 1714 a721966779be
parent 1444 ad182c8e14f7
child 2172 cf8f9180e63e
equal deleted inserted replaced
1499:fd8751c3f3ee 1714:a721966779be
       
     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 by
       
    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 its needs, then everyone can have a local repository,
       
    27 that you 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 Tk)::
       
    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 forest extension
       
   115 ````````````````````````````````````
       
   116 
       
   117 Set up the forest extension by getting a copy of the sources 
       
   118 from http://hg.akoha.org/hgforest/ and adding the following 
       
   119 lines to your ``~/.hgrc``: ::
       
   120 
       
   121    [extensions]
       
   122    hgext.forest=
       
   123    # or, if forest.py is not in the hgext dir:
       
   124    # forest=/path/to/forest.py
       
   125 
       
   126 
       
   127 More information
       
   128 ````````````````
       
   129 
       
   130 For more information about Mercurial, please refer to the Mercurial project online documentation_.
       
   131 
       
   132 .. _documentation: http://www.selenic.com/mercurial/wiki/
       
   133