The beginnings of a FAQ file

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

The beginnings of a FAQ file

manifest hash: 234ee7d9fb5cd3b0bd794e615a74f96a4cc234e0
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.0 (GNU/Linux)

iD8DBQFCuy48ywK+sNU5EO8RAmdYAJ923bFC/a6q28nVYumWsaQ+axlKawCfS7IC
kh1xVlj5OYOloicyaHDhLU4=
=7CJ2
-----END PGP SIGNATURE-----

doc/FAQ.txt

@@ -0,0 +1,214 b''
+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).