doc/FAQ.txt
author Thomas Arendsen Hein <thomas@intevation.de>
Sun, 07 Aug 2005 17:41:13 +0100
changeset 856 fbe964ae7325
parent 740 d2422f10c136
permissions -rw-r--r--
Fixed encoding of directories ending in .d or .i: One .d and .i was mixed up, and string replace method doesn't work in-place.
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
446
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
     1
Mercurial Frequently Asked Questions
449
df83b2c306ac Cleaned up some asciidoc bits in the FAQ
mpm@selenic.com
parents: 446
diff changeset
     2
====================================
446
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
     3
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
     4
Section 1: General Usage
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
     5
------------------------
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
     6
449
df83b2c306ac Cleaned up some asciidoc bits in the FAQ
mpm@selenic.com
parents: 446
diff changeset
     7
.Q. I did an "hg pull" and my working directory is empty!
446
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
     8
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
     9
There are two parts to Mercurial: the repository and the working
449
df83b2c306ac Cleaned up some asciidoc bits in the FAQ
mpm@selenic.com
parents: 446
diff changeset
    10
directory. "hg pull" pulls all new changes from a remote repository
446
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    11
into the local one but doesn't alter the working directory.
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    12
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    13
This keeps you from upsetting your work in progress, which may not be
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    14
ready to merge with the new changes you've pulled and also allows you
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    15
to manage merging more easily (see below about best practices).
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    16
449
df83b2c306ac Cleaned up some asciidoc bits in the FAQ
mpm@selenic.com
parents: 446
diff changeset
    17
To update your working directory, run "hg update". If you're sure you
df83b2c306ac Cleaned up some asciidoc bits in the FAQ
mpm@selenic.com
parents: 446
diff changeset
    18
want to update your working directory on a pull, you can also use "hg
df83b2c306ac Cleaned up some asciidoc bits in the FAQ
mpm@selenic.com
parents: 446
diff changeset
    19
pull -u". This will refuse to merge or overwrite local changes.
446
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    20
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    21
449
df83b2c306ac Cleaned up some asciidoc bits in the FAQ
mpm@selenic.com
parents: 446
diff changeset
    22
.Q. What are revision numbers, changeset IDs, and tags?
446
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    23
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    24
Mercurial will generally allow you to refer to a revision in three
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    25
ways: by revision number, by changeset ID, and by tag.
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    26
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    27
A revision number is a simple decimal number that corresponds with the
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    28
ordering of commits in the local repository. It is important to
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    29
understand that this ordering can change from machine to machine due
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    30
to Mercurial's distributed, decentralized architecture.
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    31
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    32
This is where changeset IDs come in. A changeset ID is a 160-bit
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    33
identifier that uniquely describes a changeset and its position in the
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    34
change history, regardless of which machine it's on. This is
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    35
represented to the user as a 40 digit hexadecimal number. As that
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    36
tends to be unwieldy, Mercurial will accept any unambiguous substring
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    37
of that number when specifying versions. It will also generally print
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    38
these numbers in "short form", which is the first 12 digits.
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    39
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    40
You should always use some form of changeset ID rather than the local
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    41
revision number when discussing revisions with other Mercurial users
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    42
as they may have different revision numbering on their system.
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    43
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    44
Finally, a tag is an arbitrary string that has been assigned a
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    45
correspondence to a changeset ID. This lets you refer to revisions
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    46
symbolically.
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    47
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    48
449
df83b2c306ac Cleaned up some asciidoc bits in the FAQ
mpm@selenic.com
parents: 446
diff changeset
    49
.Q. What are branches, heads, and the tip?
446
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    50
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    51
The central concept of Mercurial is branching. A 'branch' is simply
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    52
an independent line of development. In most other version control
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    53
systems, all users generally commit to the same line of development
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    54
called 'the trunk' or 'the main branch'. In Mercurial, every developer
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    55
effectively works on a private branch and there is no internal concept
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    56
of 'the main branch'.
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    57
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    58
Thus Mercurial works hard to make repeated merging between branches
449
df83b2c306ac Cleaned up some asciidoc bits in the FAQ
mpm@selenic.com
parents: 446
diff changeset
    59
easy. Simply run "hg pull" and "hg update -m" and commit the result.
446
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    60
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    61
'Heads' are simply the most recent commits on a branch. Technically,
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    62
they are changesets which have no children. Merging is the process of
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    63
joining points on two branches into one, usually at their current
449
df83b2c306ac Cleaned up some asciidoc bits in the FAQ
mpm@selenic.com
parents: 446
diff changeset
    64
heads. Use "hg heads" to find the heads in the current repository.
446
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    65
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    66
The 'tip' is the most recently changed head, and also the highest
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    67
numbered revision. If you have just made a commit, that commit will be
718
7dae73778114 Fix typos in FAQ
jdc@uwo.ca
parents: 631
diff changeset
    68
the tip. Alternately, if you have just pulled from another
446
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    69
repository, the tip of that repository becomes the current tip.
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    70
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    71
The 'tip' is the default revision for many commands such as update,
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    72
and also functions as a special symbolic tag.
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    73
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    74
449
df83b2c306ac Cleaned up some asciidoc bits in the FAQ
mpm@selenic.com
parents: 446
diff changeset
    75
.Q. How does merging work?
446
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    76
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    77
The merge process is simple. Usually you will want to merge the tip
449
df83b2c306ac Cleaned up some asciidoc bits in the FAQ
mpm@selenic.com
parents: 446
diff changeset
    78
into your working directory. Thus you run "hg update -m" and Mercurial
446
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    79
will incorporate the changes from tip into your local changes.
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    80
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    81
The first step of this process is tracing back through the history of
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    82
changesets and finding the 'common ancestor' of the two versions that
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    83
are being merged. This is done on a project-wide and a file by file
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    84
basis.
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    85
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    86
For files that have been changed in both projects, a three-way merge
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    87
is attempted to add the changes made remotely into the changes made
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    88
locally. If there are conflicts between these changes, the user is
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    89
prompted to interactively resolve them.
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    90
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    91
Mercurial uses a helper tool for this, which is usually found by the
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    92
hgmerge script. Example tools include tkdiff, kdiff3, and the classic
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    93
RCS merge.
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    94
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    95
After you've completed the merge and you're satisfied that the results
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    96
are correct, it's a good idea to commit your changes. Mercurial won't
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    97
allow you to perform another merge until you've done this commit as
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    98
that would lose important history that will be needed for future
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
    99
merges.
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   100
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   101
449
df83b2c306ac Cleaned up some asciidoc bits in the FAQ
mpm@selenic.com
parents: 446
diff changeset
   102
.Q. How do tags work in Mercurial?
446
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   103
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   104
Tags work slightly differently in Mercurial than most revision
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   105
systems. The design attempts to meet the following requirements:
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   106
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   107
- be version controlled and mergeable just like any other file
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   108
- allow signing of tags
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   109
- allow adding a tag to an already committed changeset
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   110
- allow changing tags in the future
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   111
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   112
Thus Mercurial stores tags as a file in the working dir. This file is
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   113
called .hgtags and consists of a list of changeset IDs and their
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   114
corresponding tags. To add a tag to the system, simply add a line to
449
df83b2c306ac Cleaned up some asciidoc bits in the FAQ
mpm@selenic.com
parents: 446
diff changeset
   115
this file and then commit it for it to take effect. The "hg tag"
df83b2c306ac Cleaned up some asciidoc bits in the FAQ
mpm@selenic.com
parents: 446
diff changeset
   116
command will do this for you and "hg tags" will show the currently
446
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   117
effective tags.
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   118
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   119
Note that because tags refer to changeset IDs and the changeset ID is
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   120
effectively the sum of all the contents of the repository for that
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   121
change, it is impossible in Mercurial to simultaneously commit and add
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   122
a tag. Thus tagging a revision must be done as a second step.
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   123
449
df83b2c306ac Cleaned up some asciidoc bits in the FAQ
mpm@selenic.com
parents: 446
diff changeset
   124
455
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   125
.Q. What if I want to just keep local tags?
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   126
631
a287f6cd9c6b Update documentation of hg tag
Radoslaw Szkodzinski <astralstorm@gorzow.mm.pl>
parents: 456
diff changeset
   127
You can use "hg tag" command with an option "-l" or "--local". This
a287f6cd9c6b Update documentation of hg tag
Radoslaw Szkodzinski <astralstorm@gorzow.mm.pl>
parents: 456
diff changeset
   128
will store the tag in the file .hg/localtags, which will not be
a287f6cd9c6b Update documentation of hg tag
Radoslaw Szkodzinski <astralstorm@gorzow.mm.pl>
parents: 456
diff changeset
   129
distributed or versioned. The format of this file is identical to the
a287f6cd9c6b Update documentation of hg tag
Radoslaw Szkodzinski <astralstorm@gorzow.mm.pl>
parents: 456
diff changeset
   130
one of .hgtags and the tags stored there are handled the same.
455
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   131
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   132
449
df83b2c306ac Cleaned up some asciidoc bits in the FAQ
mpm@selenic.com
parents: 446
diff changeset
   133
.Q. How do tags work with multiple heads?
446
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   134
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   135
The tags that are in effect at any given time are the tags specified
455
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   136
in each head, with heads closer to the tip taking precedence. Local
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   137
tags override all other tags.
446
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   138
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   139
449
df83b2c306ac Cleaned up some asciidoc bits in the FAQ
mpm@selenic.com
parents: 446
diff changeset
   140
.Q. What are some best practices for distributed development with Mercurial?
446
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   141
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   142
First, merge often! This makes merging easier for everyone and you
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   143
find out about conflicts (which are often rooted in incompatible
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   144
design decisions) earlier.
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   145
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   146
Second, don't hesitate to use multiple trees locally. Mercurial makes
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   147
this fast and light-weight. Typical usage is to have an incoming tree,
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   148
an outgoing tree, and a separate tree for each area being worked on.
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   149
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   150
The incoming tree is best maintained as a pristine copy of the
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   151
upstream repository. This works as a cache so that you don't have to
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   152
pull multiple copies over the network. No need to check files out here
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   153
as you won't be changing them.
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   154
718
7dae73778114 Fix typos in FAQ
jdc@uwo.ca
parents: 631
diff changeset
   155
The outgoing tree contains all the changes you intend for merge into
449
df83b2c306ac Cleaned up some asciidoc bits in the FAQ
mpm@selenic.com
parents: 446
diff changeset
   156
upsteam. Publish this tree with 'hg serve" or hgweb.cgi or use 'hg
df83b2c306ac Cleaned up some asciidoc bits in the FAQ
mpm@selenic.com
parents: 446
diff changeset
   157
push" to push it to another publicly availabe repository.
446
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   158
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   159
Then, for each feature you work on, create a new tree. Commit early
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   160
and commit often, merge with incoming regularly, and once you're
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   161
satisfied with your feature, pull the changes into your outgoing tree.
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   162
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   163
449
df83b2c306ac Cleaned up some asciidoc bits in the FAQ
mpm@selenic.com
parents: 446
diff changeset
   164
.Q. How do I import from a repository created in a different SCM?
446
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   165
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   166
Take a look at contrib/convert-repo. This is an extensible
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   167
framework for converting between repository types.
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   168
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   169
449
df83b2c306ac Cleaned up some asciidoc bits in the FAQ
mpm@selenic.com
parents: 446
diff changeset
   170
.Q. What about Windows support?
446
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   171
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   172
Patches to support Windows are being actively integrated, a fully
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   173
working Windows version is probably not far off
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   174
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   175
456
d6ac88a738c4 More FAQ bits.
mpm@selenic.com
parents: 455
diff changeset
   176
Section 2: Bugs and Features
d6ac88a738c4 More FAQ bits.
mpm@selenic.com
parents: 455
diff changeset
   177
----------------------------
d6ac88a738c4 More FAQ bits.
mpm@selenic.com
parents: 455
diff changeset
   178
d6ac88a738c4 More FAQ bits.
mpm@selenic.com
parents: 455
diff changeset
   179
.Q. I found a bug, what do I do?
d6ac88a738c4 More FAQ bits.
mpm@selenic.com
parents: 455
diff changeset
   180
d6ac88a738c4 More FAQ bits.
mpm@selenic.com
parents: 455
diff changeset
   181
Report it to the mercurial mailing list, mercurial@selenic.com.
d6ac88a738c4 More FAQ bits.
mpm@selenic.com
parents: 455
diff changeset
   182
d6ac88a738c4 More FAQ bits.
mpm@selenic.com
parents: 455
diff changeset
   183
d6ac88a738c4 More FAQ bits.
mpm@selenic.com
parents: 455
diff changeset
   184
.Q. What should I include in my bug report?
d6ac88a738c4 More FAQ bits.
mpm@selenic.com
parents: 455
diff changeset
   185
d6ac88a738c4 More FAQ bits.
mpm@selenic.com
parents: 455
diff changeset
   186
Enough information to reproduce or diagnose the bug. If you can, try
d6ac88a738c4 More FAQ bits.
mpm@selenic.com
parents: 455
diff changeset
   187
using the hg -v and hg -d switches to figure out exactly what
d6ac88a738c4 More FAQ bits.
mpm@selenic.com
parents: 455
diff changeset
   188
Mercurial is doing.
d6ac88a738c4 More FAQ bits.
mpm@selenic.com
parents: 455
diff changeset
   189
d6ac88a738c4 More FAQ bits.
mpm@selenic.com
parents: 455
diff changeset
   190
If you can reproduce the bug in a simple repository, that is very
d6ac88a738c4 More FAQ bits.
mpm@selenic.com
parents: 455
diff changeset
   191
helpful. The best is to create a simple shell script to automate this
d6ac88a738c4 More FAQ bits.
mpm@selenic.com
parents: 455
diff changeset
   192
process, which can then be added to our test suite.
d6ac88a738c4 More FAQ bits.
mpm@selenic.com
parents: 455
diff changeset
   193
d6ac88a738c4 More FAQ bits.
mpm@selenic.com
parents: 455
diff changeset
   194
d6ac88a738c4 More FAQ bits.
mpm@selenic.com
parents: 455
diff changeset
   195
.Q. Can Mercurial do <x>?
d6ac88a738c4 More FAQ bits.
mpm@selenic.com
parents: 455
diff changeset
   196
d6ac88a738c4 More FAQ bits.
mpm@selenic.com
parents: 455
diff changeset
   197
If you'd like to request a feature, send your request to
d6ac88a738c4 More FAQ bits.
mpm@selenic.com
parents: 455
diff changeset
   198
mercurial@selenic.com. As Mercurial is still very new, there are
718
7dae73778114 Fix typos in FAQ
jdc@uwo.ca
parents: 631
diff changeset
   199
certainly features it is missing and you can give us feedback on how
456
d6ac88a738c4 More FAQ bits.
mpm@selenic.com
parents: 455
diff changeset
   200
best to implement them.
d6ac88a738c4 More FAQ bits.
mpm@selenic.com
parents: 455
diff changeset
   201
d6ac88a738c4 More FAQ bits.
mpm@selenic.com
parents: 455
diff changeset
   202
d6ac88a738c4 More FAQ bits.
mpm@selenic.com
parents: 455
diff changeset
   203
Section 3: Technical
446
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   204
--------------------
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   205
449
df83b2c306ac Cleaned up some asciidoc bits in the FAQ
mpm@selenic.com
parents: 446
diff changeset
   206
.Q. What limits does Mercurial have?
446
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   207
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   208
Mercurial currently assumes that single files, indices, and manifests
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   209
can fit in memory for efficiency.
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   210
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   211
Offsets in revlogs are currently tracked with 32 bits, so a revlog for
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   212
a single file can currently not grow beyond 4G.
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   213
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   214
There should otherwise be no limits on file name length, file size,
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   215
file contents, number of files, or number of revisions.
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   216
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   217
The network protocol is big-endian.
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   218
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   219
File names cannot contain the null character. Committer addresses
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   220
cannot contain newlines.
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   221
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   222
Mercurial is primarily developed for UNIX systems, so some UNIXisms
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   223
may be present in ports.
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   224
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   225
455
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   226
.Q. How does Mercurial store its data?
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   227
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   228
The fundamental storage type in Mercurial is a "revlog". A revlog is
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   229
the set of all revisions of a named object. Each revision is either
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   230
stored compressed in its entirety or as a compressed binary delta
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   231
against the previous version. The decision of when to store a full
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   232
version is made based on how much data would be needed to reconstruct
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   233
the file. This lets us ensure that we never need to read huge amounts
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   234
of data to reconstruct a object, regardless of how many revisions of it
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   235
we store.
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   236
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   237
In fact, we should always be able to do it with a single read,
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   238
provided we know when and where to read. This is where the index comes
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   239
in. Each revlog has an index containing a special hash (nodeid) of the
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   240
text, hashes for its parents, and where and how much of the revlog
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   241
data we need to read to reconstruct it. Thus, with one read of the
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   242
index and one read of the data, we can reconstruct any version in time
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   243
proportional to the object size.
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   244
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   245
Similarly, revlogs and their indices are append-only. This means that
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   246
adding a new version is also O(1) seeks.
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   247
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   248
Revlogs are used to represent all revisions of files, manifests, and
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   249
changesets. Compression for typical objects with lots of revisions can
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   250
range from 100 to 1 for things like project makefiles to over 2000 to
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   251
1 for objects like the manifest.
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   252
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   253
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   254
.Q. How are manifests and changesets stored?
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   255
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   256
A manifest is simply a list of all files in a given revision of a
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   257
project along with the nodeids of the corresponding file revisions. So
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   258
grabbing a given version of the project means simply looking up its
718
7dae73778114 Fix typos in FAQ
jdc@uwo.ca
parents: 631
diff changeset
   259
manifest and reconstructing all the file revisions pointed to by it.
446
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   260
455
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   261
A changeset is a list of all files changed in a check-in along with a
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   262
change description and some metadata like user and date. It also
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   263
contains a nodeid to the relevent revision of the manifest.
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   264
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   265
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   266
.Q. How do Mercurial hashes get calculated?
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   267
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   268
Mercurial hashes both the contents of an object and the hash of its
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   269
parents to create an identifier that uniquely identifies an object's
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   270
contents and history. This greatly simplifies merging of histories
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   271
because it avoid graph cycles that can occur when a object is reverted
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   272
to an earlier state.
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   273
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   274
All file revisions have an associated hash value. These are listed in
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   275
the manifest of a given project revision, and the manifest hash is
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   276
listed in the changeset. The changeset hash is again a hash of the
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   277
changeset contents and its parents, so it uniquely identifies the
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   278
entire history of the project to that point.
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   279
446
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   280
455
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   281
.Q. What checks are there on repository integrity?
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   282
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   283
Every time a revlog object is retrieved, it is checked against its
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   284
hash for integrity. It is also incidentally doublechecked by the
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   285
Adler32 checksum used by the underlying zlib compression.
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   286
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   287
Running 'hg verify' decompresses and reconstitutes each revision of
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   288
each object in the repository and cross-checks all of the index
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   289
metadata with those contents.
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   290
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   291
But this alone is not enough to ensure that someone hasn't tampered
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   292
with a repository. For that, you need cryptographic signing.
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   293
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   294
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   295
.Q. How does signing work with Mercurial?
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   296
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   297
Take a look at the hgeditor script for an example. The basic idea is
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   298
to use GPG to sign the manifest ID inside that changelog entry. The
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   299
manifest ID is a recursive hash of all of the files in the system and
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   300
their complete history, and thus signing the manifest hash signs the
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   301
entire project contents.
446
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   302
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   303
449
df83b2c306ac Cleaned up some asciidoc bits in the FAQ
mpm@selenic.com
parents: 446
diff changeset
   304
.Q. What about hash collisions? What about weaknesses in SHA1?
446
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   305
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   306
The SHA1 hashes are large enough that the odds of accidental hash collision
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   307
are negligible for projects that could be handled by the human race.
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   308
The known weaknesses in SHA1 are currently still not practical to
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   309
attack, and Mercurial will switch to SHA256 hashing before that
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   310
becomes a realistic concern.
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   311
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   312
Collisions with the "short hashes" are not a concern as they're always
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   313
checked for ambiguity and are still long enough that they're not
8cc0ee3f18fb The beginnings of a FAQ file
mpm@selenic.com
parents:
diff changeset
   314
likely to happen for reasonably-sized projects (< 1M changes).
455
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   315
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   316
8d43dfdfb514 More FAQ updates
mpm@selenic.com
parents: 449
diff changeset
   317