=== 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 [[ChangeSetID|changeset ID]], and by [[Tag|tag]].

A [[RevisionNumber|revision number]] is a simple decimal number that corresponds with the
ordering of commits in the local [[Repository|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|tag]] is an arbitrary string that has been assigned a
correspondence to a changeset ID. This lets you refer to [[Revision|revisions]]
symbolically.

=== What are cloning, pulling, and pushing? ===

In many other version control systems, all developers commit changes
to a single, centralized repository. In Mercurial, every developer
typically works in his or her own repository. A fundamental concept
of Mercurial is transferring [[ChangeSet|changesets]] among [[Repository|repositories]]. This is
accomplished through the clone, push, and pull
operations (see also [[CommunicatingChanges]]).

To begin a task on an existing project, a developer will typically
create a local copy of the repository using the {{{hg clone}}} command.
This operation creates a new repository containing all the
files and all of their history.

If another developer has made changes to her repository, you can pull
her changes into your repository using the {{{hg pull}}} command. If
you have made changes to your repository and you wish to transfer them
to another repository (say, to a shared repository), you would do this
using the {{{hg push}}} command.

=== What are branches, merges, heads, and the tip? ===

In the simplest case, history consists of a linear sequence of [[ChangeSet|changesets]].
In this case, every changeset (except for the first and last) has one parent
and one child. For a variety of reasons, it is possible for the history graph to split into
two or more independent lines of development. When this occurs, the history graph
is said to have a [[Branch|branch]]. Where a branch occurs, a changeset has two or
more children.

When two lines of development are joined into a single line, a [[Merge|merge]] is
said to have occurred. Where a merge occurs, a changeset has two parents.
If a line of development is not merged into another, the last changeset on
that line is referred to as the [[Head|head]] of that branch. Every [[Repository|repository]]
always includes one or more heads. Heads have no children. Use the {{{hg heads}}}
command to list the heads of the current repository.

The [[Tip|tip]] is the changeset added to the repository most recently.
If you have just made a commit, that commit will be
the tip. Alternately, if you have just pulled from another
repository, the tip of that repository becomes the new tip.
Use {{{hg tip}}} to show the tip of the repository.

The tip is always a head. If there are multiple heads in a repository, only one of
them is the tip. Within a repository, changesets
are numbered sequentially, so the tip has the highest sequence number. The word
"tip" functions as a special [[Tag|tag]] to denote the tip changeset, and it can
be used anywhere a changeset ID or tag is valid.

The following diagram illustrates these concepts.

{{{#!dot
digraph {
   rankdir = LR
   node [shape=box]
   "rev 0:838e" -> "rev 1:34ef" 
   "rev 1:34ef" -> "rev 2:4563"
   "rev 1:34ef" -> "rev 3:fe56"
   "rev 2:4563" -> "rev 4:ac98"
   "rev 3:fe56" -> "rev 4:ac98"
   "rev 4:ac98" -> "rev 5:0345"
   "rev 4:ac98" -> "rev 6:19e3"
   "rev 4:ac98" -> "rev 7:8e92"
   label="example history"
}
}}}

The history has branched at revs 1:34ef and 4:ac98, and a merge has occurred at
rev 4:ac98. Revs 5:0345, 6:19e3, and 7:8e92 are heads, and 7:8e92 is the tip.

Note that while {{{hg tip}}} shows the tip and {{{hg heads}}} shows the
heads of the repository, the {{{hg branch}}} and {{{hg branches}}} commands
do not list the branch changesets as described above. Instead, they show
changesets corresponding to branches that have been given names. See NamedBranches.

The term "branch" has other meanings as well. See [[Branch]] for a fuller discussion.