doc/book/annexes/mercurial.rst
author Guillaume Vandevelde <gvandevelde@logilab.fr>
Thu, 13 Feb 2020 13:56:12 +0100
branch3.26
changeset 12876 fe9bd0e937e4
parent 10491 c67bcee93248
child 12854 87c94f2a3103
permissions -rw-r--r--
[pkg] version 3.26.15
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
     1
.. -*- coding: utf-8 -*-
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
     2
105
300166b41ea9 [doc] Moved installation from mercurial forest in appendix. Cleaned installation section but needs improvements.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 104
diff changeset
     3
.. _MercurialPresentation:
98
f756ead5746a [doc] Initial translation of first two section in installation chapter.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 93
diff changeset
     4
208
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
     5
Introducing Mercurial
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
     6
=====================
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
     7
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
     8
Introduction
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
     9
````````````
208
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
    10
Mercurial_ manages a distributed repository containing revisions
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
    11
trees (each revision indicates the changes required to obtain the
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
    12
next, and so on). Locally, we have a repository containing revisions
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
    13
tree, and a working directory. It is possible
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
    14
to put in its working directory, one of the versions of its local repository,
2172
cf8f9180e63e delete-trailing-whitespace
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 1714
diff changeset
    15
modify and then push it in its repository.
208
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
    16
It is also possible to get revisions from another repository or to export
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
    17
its own revisions from the local repository to another repository.
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    18
267
843e0b1bf991 [doc] simpler install and mercurial instructions
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 208
diff changeset
    19
.. _Mercurial: http://www.selenic.com/mercurial/
208
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
    20
9917
a98e60464c26 [book] stop talking about the hg `forest` extension
Julien Cristau <julien.cristau@logilab.fr>
parents: 2172
diff changeset
    21
In contrast to CVS/Subversion, we usually create a repository per
208
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
    22
project to manage.
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    23
208
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
    24
In a collaborative development, we usually create a central repository
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
    25
accessible to all developers of the project. These central repository is used
9917
a98e60464c26 [book] stop talking about the hg `forest` extension
Julien Cristau <julien.cristau@logilab.fr>
parents: 2172
diff changeset
    26
as a reference. According to their needs, everyone can have a local repository,
a98e60464c26 [book] stop talking about the hg `forest` extension
Julien Cristau <julien.cristau@logilab.fr>
parents: 2172
diff changeset
    27
that they will have to synchronize with the central repository from time to time.
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    28
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    29
208
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
    30
Major commands
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
    31
``````````````
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
    32
* Create a local repository::
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    33
267
843e0b1bf991 [doc] simpler install and mercurial instructions
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 208
diff changeset
    34
     hg clone ssh://myhost//home/src/repo
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    35
9917
a98e60464c26 [book] stop talking about the hg `forest` extension
Julien Cristau <julien.cristau@logilab.fr>
parents: 2172
diff changeset
    36
* See the contents of the local repository (graphical tool in Qt)::
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    37
208
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
    38
     hgview
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    39
208
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
    40
* Add a sub-directory or file in the current directory::
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    41
267
843e0b1bf991 [doc] simpler install and mercurial instructions
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 208
diff changeset
    42
     hg add subdir
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    43
208
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
    44
* Move to the working directory a specific revision (or last
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
    45
  revision) from the local repository::
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    46
208
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
    47
     hg update [identifier-revision]
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
    48
     hg up [identifier-revision]
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    49
208
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
    50
* Get in its local repository, the tree of revisions contained in a
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
    51
  remote repository (this does not change the local directory)::
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    52
267
843e0b1bf991 [doc] simpler install and mercurial instructions
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 208
diff changeset
    53
     hg pull ssh://myhost//home/src/repo
843e0b1bf991 [doc] simpler install and mercurial instructions
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 208
diff changeset
    54
     hg pull -u ssh://myhost//home/src/repo # equivalent to pull + update
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    55
208
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
    56
* See what are the heads of branches of the local repository if a `pull`
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
    57
  returned a new branch::
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    58
208
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
    59
     hg heads
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    60
208
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
    61
* Submit the working directory in the local repository (and create a new
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
    62
  revision)::
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    63
208
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
    64
     hg commit
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
    65
     hg ci
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    66
208
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
    67
* Merge with the mother revision of local directory, another revision from
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
    68
  the local respository (the new revision will be then two mothers
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
    69
  revisions)::
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    70
208
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
    71
     hg merge identifier-revision
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    72
208
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
    73
* Export to a remote repository, the tree of revisions in its content
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
    74
  local respository (this does not change the local directory)::
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    75
267
843e0b1bf991 [doc] simpler install and mercurial instructions
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 208
diff changeset
    76
     hg push ssh://myhost//home/src/repo
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    77
208
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
    78
* See what local revisions are not in another repository::
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    79
267
843e0b1bf991 [doc] simpler install and mercurial instructions
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 208
diff changeset
    80
     hg outgoing ssh://myhost//home/src/repo
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    81
208
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
    82
* See what are the revisions of a repository not found locally::
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    83
267
843e0b1bf991 [doc] simpler install and mercurial instructions
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 208
diff changeset
    84
     hg incoming ssh://myhost//home/src/repo
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    85
2172
cf8f9180e63e delete-trailing-whitespace
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 1714
diff changeset
    86
* See what is the revision of the local repository which has been taken out
208
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
    87
  from the working directory and amended::
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    88
208
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
    89
     hg parent
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    90
208
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
    91
* See the differences between the working directory and the mother revision
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
    92
  of the local repository, possibly to submit them in the local repository::
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    93
208
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
    94
     hg diff
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
    95
     hg commit-tool
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
    96
     hg ct
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    97
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    98
208
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
    99
Best Practices
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
   100
``````````````
267
843e0b1bf991 [doc] simpler install and mercurial instructions
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 208
diff changeset
   101
* Remember to `hg pull -u` regularly, and particularly before
208
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
   102
   a `hg commit`.
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   103
267
843e0b1bf991 [doc] simpler install and mercurial instructions
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 208
diff changeset
   104
* Remember to `hg push` when your repository contains a version
208
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
   105
  relatively stable of your changes.
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   106
267
843e0b1bf991 [doc] simpler install and mercurial instructions
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 208
diff changeset
   107
* If a `hg pull -u` created a new branch head:
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   108
267
843e0b1bf991 [doc] simpler install and mercurial instructions
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 208
diff changeset
   109
   1. find its identifier with `hg head`
208
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
   110
   2. merge with `hg merge`
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
   111
   3. `hg ci`
30762142841f [doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 127
diff changeset
   112
   4. `hg push`
93
9c919a47e140 [doc] total file reorganisation - phase 1 complete
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   113
9917
a98e60464c26 [book] stop talking about the hg `forest` extension
Julien Cristau <julien.cristau@logilab.fr>
parents: 2172
diff changeset
   114
Installation of the guestrepo extension
a98e60464c26 [book] stop talking about the hg `forest` extension
Julien Cristau <julien.cristau@logilab.fr>
parents: 2172
diff changeset
   115
```````````````````````````````````````
127
ae611743f5c6 [doc] divided book in parts
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 105
diff changeset
   116
9917
a98e60464c26 [book] stop talking about the hg `forest` extension
Julien Cristau <julien.cristau@logilab.fr>
parents: 2172
diff changeset
   117
Set up the guestrepo extension by getting a copy of the sources
a98e60464c26 [book] stop talking about the hg `forest` extension
Julien Cristau <julien.cristau@logilab.fr>
parents: 2172
diff changeset
   118
from https://bitbucket.org/selinc/guestrepo and adding the following
267
843e0b1bf991 [doc] simpler install and mercurial instructions
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 208
diff changeset
   119
lines to your ``~/.hgrc``: ::
843e0b1bf991 [doc] simpler install and mercurial instructions
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 208
diff changeset
   120
843e0b1bf991 [doc] simpler install and mercurial instructions
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 208
diff changeset
   121
   [extensions]
9917
a98e60464c26 [book] stop talking about the hg `forest` extension
Julien Cristau <julien.cristau@logilab.fr>
parents: 2172
diff changeset
   122
   guestrepo=/path/to/guestrepo/guestrepo
267
843e0b1bf991 [doc] simpler install and mercurial instructions
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 208
diff changeset
   123
843e0b1bf991 [doc] simpler install and mercurial instructions
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 208
diff changeset
   124
843e0b1bf991 [doc] simpler install and mercurial instructions
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 208
diff changeset
   125
More information
843e0b1bf991 [doc] simpler install and mercurial instructions
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 208
diff changeset
   126
````````````````
843e0b1bf991 [doc] simpler install and mercurial instructions
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 208
diff changeset
   127
843e0b1bf991 [doc] simpler install and mercurial instructions
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 208
diff changeset
   128
For more information about Mercurial, please refer to the Mercurial project online documentation_.
843e0b1bf991 [doc] simpler install and mercurial instructions
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 208
diff changeset
   129
843e0b1bf991 [doc] simpler install and mercurial instructions
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 208
diff changeset
   130
.. _documentation: http://www.selenic.com/mercurial/wiki/
843e0b1bf991 [doc] simpler install and mercurial instructions
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 208
diff changeset
   131