doc/FAQ.txt
author Thomas Arendsen Hein <thomas@intevation.de>
Wed, 10 Aug 2005 06:47:46 +0100
changeset 862 d70c1c31fd45
parent 740 d2422f10c136
permissions -rw-r--r--
Fix 3-way-merge of original parent, workdir and new parent. The dirstate has to match what is in the repository (what would be checked out with 'hg update -C'), because the resulting file may be identical to the new parent, or it may be completely different. Previously the dirstate wasn't updated, so if you changed the file to look like the original parent, it might be considered unmodified relative to the new parent.
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