|
|
Mercurial Frequently Asked Questions
|
|
|
====================================
|
|
|
|
|
|
Section 1: General Usage
|
|
|
------------------------
|
|
|
|
|
|
.Q. I did an "hg pull" and my working directory is empty!
|
|
|
|
|
|
There are two parts to Mercurial: the repository and the working
|
|
|
directory. "hg pull" pulls all new changes from a remote repository
|
|
|
into the local one but doesn't alter the working directory.
|
|
|
|
|
|
This keeps you from upsetting your work in progress, which may not be
|
|
|
ready to merge with the new changes you've pulled and also allows you
|
|
|
to manage merging more easily (see below about best practices).
|
|
|
|
|
|
To update your working directory, run "hg update". If you're sure you
|
|
|
want to update your working directory on a pull, you can also use "hg
|
|
|
pull -u". This will refuse to merge or overwrite local changes.
|
|
|
|
|
|
|
|
|
.Q. What are revision numbers, changeset IDs, and tags?
|
|
|
|
|
|
Mercurial will generally allow you to refer to a revision in three
|
|
|
ways: by revision number, by changeset ID, and by tag.
|
|
|
|
|
|
A revision number is a simple decimal number that corresponds with the
|
|
|
ordering of commits in the local repository. It is important to
|
|
|
understand that this ordering can change from machine to machine due
|
|
|
to Mercurial's distributed, decentralized architecture.
|
|
|
|
|
|
This is where changeset IDs come in. A changeset ID is a 160-bit
|
|
|
identifier that uniquely describes a changeset and its position in the
|
|
|
change history, regardless of which machine it's on. This is
|
|
|
represented to the user as a 40 digit hexadecimal number. As that
|
|
|
tends to be unwieldy, Mercurial will accept any unambiguous substring
|
|
|
of that number when specifying versions. It will also generally print
|
|
|
these numbers in "short form", which is the first 12 digits.
|
|
|
|
|
|
You should always use some form of changeset ID rather than the local
|
|
|
revision number when discussing revisions with other Mercurial users
|
|
|
as they may have different revision numbering on their system.
|
|
|
|
|
|
Finally, a tag is an arbitrary string that has been assigned a
|
|
|
correspondence to a changeset ID. This lets you refer to revisions
|
|
|
symbolically.
|
|
|
|
|
|
|
|
|
.Q. What are branches, heads, and the tip?
|
|
|
|
|
|
The central concept of Mercurial is branching. A 'branch' is simply
|
|
|
an independent line of development. In most other version control
|
|
|
systems, all users generally commit to the same line of development
|
|
|
called 'the trunk' or 'the main branch'. In Mercurial, every developer
|
|
|
effectively works on a private branch and there is no internal concept
|
|
|
of 'the main branch'.
|
|
|
|
|
|
Thus Mercurial works hard to make repeated merging between branches
|
|
|
easy. Simply run "hg pull" and "hg update -m" and commit the result.
|
|
|
|
|
|
'Heads' are simply the most recent commits on a branch. Technically,
|
|
|
they are changesets which have no children. Merging is the process of
|
|
|
joining points on two branches into one, usually at their current
|
|
|
heads. Use "hg heads" to find the heads in the current repository.
|
|
|
|
|
|
The 'tip' is the most recently changed head, and also the highest
|
|
|
numbered revision. If you have just made a commit, that commit will be
|
|
|
the head. Alternately, if you have just pulled from another
|
|
|
repository, the tip of that repository becomes the current tip.
|
|
|
|
|
|
The 'tip' is the default revision for many commands such as update,
|
|
|
and also functions as a special symbolic tag.
|
|
|
|
|
|
|
|
|
.Q. How does merging work?
|
|
|
|
|
|
The merge process is simple. Usually you will want to merge the tip
|
|
|
into your working directory. Thus you run "hg update -m" and Mercurial
|
|
|
will incorporate the changes from tip into your local changes.
|
|
|
|
|
|
The first step of this process is tracing back through the history of
|
|
|
changesets and finding the 'common ancestor' of the two versions that
|
|
|
are being merged. This is done on a project-wide and a file by file
|
|
|
basis.
|
|
|
|
|
|
For files that have been changed in both projects, a three-way merge
|
|
|
is attempted to add the changes made remotely into the changes made
|
|
|
locally. If there are conflicts between these changes, the user is
|
|
|
prompted to interactively resolve them.
|
|
|
|
|
|
Mercurial uses a helper tool for this, which is usually found by the
|
|
|
hgmerge script. Example tools include tkdiff, kdiff3, and the classic
|
|
|
RCS merge.
|
|
|
|
|
|
After you've completed the merge and you're satisfied that the results
|
|
|
are correct, it's a good idea to commit your changes. Mercurial won't
|
|
|
allow you to perform another merge until you've done this commit as
|
|
|
that would lose important history that will be needed for future
|
|
|
merges.
|
|
|
|
|
|
|
|
|
.Q. How do tags work in Mercurial?
|
|
|
|
|
|
Tags work slightly differently in Mercurial than most revision
|
|
|
systems. The design attempts to meet the following requirements:
|
|
|
|
|
|
- be version controlled and mergeable just like any other file
|
|
|
- allow signing of tags
|
|
|
- allow adding a tag to an already committed changeset
|
|
|
- allow changing tags in the future
|
|
|
|
|
|
Thus Mercurial stores tags as a file in the working dir. This file is
|
|
|
called .hgtags and consists of a list of changeset IDs and their
|
|
|
corresponding tags. To add a tag to the system, simply add a line to
|
|
|
this file and then commit it for it to take effect. The "hg tag"
|
|
|
command will do this for you and "hg tags" will show the currently
|
|
|
effective tags.
|
|
|
|
|
|
Note that because tags refer to changeset IDs and the changeset ID is
|
|
|
effectively the sum of all the contents of the repository for that
|
|
|
change, it is impossible in Mercurial to simultaneously commit and add
|
|
|
a tag. Thus tagging a revision must be done as a second step.
|
|
|
|
|
|
|
|
|
.Q. How do tags work with multiple heads?
|
|
|
|
|
|
The tags that are in effect at any given time are the tags specified
|
|
|
in each head, with heads closer to the tip taking precedence.
|
|
|
|
|
|
|
|
|
.Q. What are some best practices for distributed development with Mercurial?
|
|
|
|
|
|
First, merge often! This makes merging easier for everyone and you
|
|
|
find out about conflicts (which are often rooted in incompatible
|
|
|
design decisions) earlier.
|
|
|
|
|
|
Second, don't hesitate to use multiple trees locally. Mercurial makes
|
|
|
this fast and light-weight. Typical usage is to have an incoming tree,
|
|
|
an outgoing tree, and a separate tree for each area being worked on.
|
|
|
|
|
|
The incoming tree is best maintained as a pristine copy of the
|
|
|
upstream repository. This works as a cache so that you don't have to
|
|
|
pull multiple copies over the network. No need to check files out here
|
|
|
as you won't be changing them.
|
|
|
|
|
|
The outgoing tree contains all the changes you intend for merger into
|
|
|
upsteam. Publish this tree with 'hg serve" or hgweb.cgi or use 'hg
|
|
|
push" to push it to another publicly availabe repository.
|
|
|
|
|
|
Then, for each feature you work on, create a new tree. Commit early
|
|
|
and commit often, merge with incoming regularly, and once you're
|
|
|
satisfied with your feature, pull the changes into your outgoing tree.
|
|
|
|
|
|
|
|
|
.Q. How do I import from a repository created in a different SCM?
|
|
|
|
|
|
Take a look at contrib/convert-repo. This is an extensible
|
|
|
framework for converting between repository types.
|
|
|
|
|
|
|
|
|
.Q. What about Windows support?
|
|
|
|
|
|
Patches to support Windows are being actively integrated, a fully
|
|
|
working Windows version is probably not far off
|
|
|
|
|
|
|
|
|
Section 2: Technical
|
|
|
--------------------
|
|
|
|
|
|
.Q. What limits does Mercurial have?
|
|
|
|
|
|
Mercurial currently assumes that single files, indices, and manifests
|
|
|
can fit in memory for efficiency.
|
|
|
|
|
|
Offsets in revlogs are currently tracked with 32 bits, so a revlog for
|
|
|
a single file can currently not grow beyond 4G.
|
|
|
|
|
|
There should otherwise be no limits on file name length, file size,
|
|
|
file contents, number of files, or number of revisions.
|
|
|
|
|
|
The network protocol is big-endian.
|
|
|
|
|
|
File names cannot contain the null character. Committer addresses
|
|
|
cannot contain newlines.
|
|
|
|
|
|
Mercurial is primarily developed for UNIX systems, so some UNIXisms
|
|
|
may be present in ports.
|
|
|
|
|
|
|
|
|
.Q. How does signing work?
|
|
|
|
|
|
Take a look at the hgeditor script for an example. The basic idea
|
|
|
is to sign the manifest ID inside that changelog entry. The manifest
|
|
|
ID is a recursive hash of all of the files in the system and their
|
|
|
complete history, and thus signing the manifest hash signs the entire
|
|
|
project to that point.
|
|
|
|
|
|
More precisely: each file hash is an SHA1 hash of the contents of that
|
|
|
file and the hashes of its parent revisions. The manifest contains a
|
|
|
list of each file in the project along with its current file hash.
|
|
|
This manifest is hashed similarly to the file hashes, incorporating
|
|
|
the hashes of the parent revisions.
|
|
|
|
|
|
|
|
|
.Q. What about hash collisions? What about weaknesses in SHA1?
|
|
|
|
|
|
The SHA1 hashes are large enough that the odds of accidental hash collision
|
|
|
are negligible for projects that could be handled by the human race.
|
|
|
The known weaknesses in SHA1 are currently still not practical to
|
|
|
attack, and Mercurial will switch to SHA256 hashing before that
|
|
|
becomes a realistic concern.
|
|
|
|
|
|
Collisions with the "short hashes" are not a concern as they're always
|
|
|
checked for ambiguity and are still long enough that they're not
|
|
|
likely to happen for reasonably-sized projects (< 1M changes).
|
|
|
|