Diff for "UnderstandingMercurial"

Mercurial's decentralized development model can be confusing to new users. This page attempts to illustate some of the basic concepts. See the ["Tutorial"] for step-by-step instructions.

TableOfContents

What's in a Repository

Mercurial repositories contain a working directory coupled with a store:

The store contains the complete history of the project. Unlike traditional SCMs, where there's only one central copy of this history, every working directory is paired with a private copy of the history. This allows development to go on in parallel.

The working directory contains a copy of the project's files at a given point in time (eg rev 2), ready for editing. Because tags and ignored files are revision-controlled, they are also included.

Committing Changes

When you commit, the state of the working directory relative to its parents is recorded as a new revision:

Note here that revision 4 is a branch off revision 2, which was the revision in the working directory. Now revision 4 is the working directory's parent.

Revisions, Changesets, Heads, and Tip

Mercurial groups related changes to multiple files into single atomic changesets, which are revisions of the whole project. These each get a sequential revision number. Because Mercurial allows distributed parallel development, these revision numbers may disagree between users. So Mercurial also assigns each revision a global changeset ID. Changeset IDs are 40-digit hexadecimal numbers, but they can be abbreviated to any unambiguous prefix, like "e38487".

Branches and merges in the revision history can occur at any point. Each unmerged branch creates a new head of the revision history. Here, revisions 5 and 6 are heads. Mercurial considers revision 6 to be the tip of the repository, the head with the highest revision number.

Cloning, Making Changes, Merging, and Pulling

Let's start with a user Alice, who has a store that looks like:

Bob clones this repo, and ends up with a complete copy of Alice's store (though his working directory is independent!):

Bob then commits a couple changes:

Alice then makes her own change in parallel:

Bob then pulls Alice's repo to synchronize. This copies all of Alice's changes into Bob's repo:

Because Alice's g is the newest head in Bob's repository, it's now the tip. Bob then does a merge which combines the last change he was working on (f) with the tip, commits the result, and ends up with:

Now if Alice pulls from Bob, she will get Bob's changes e, f, and h, and they will be fully synchronized:

A Decentralized System

Mercurial is a completely decentralized system, and thus has no internal notion of a central repository. Thus users are free to define their own topologies for sharing changes:

For a hands-on introduction to using Mercurial, see the ["Tutorial"].