FAQ.txt
214 lines
| 8.6 KiB
| text/plain
|
TextLexer
/ doc / FAQ.txt
|
r446 | 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 is the difference between 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). | ||||