Mercurial basics

hg init

"marks" files to be added

on the next "commit"

a "revision" or "changeset" contains the state of all the files in the repository at commit time

each revision has a

unique "hash"

or "revision id"

the revision id is a 40 digit hex number

whose value depends on

• the revision contents
• the commit message
• the current time
• the state of the moon :-)

e.g. 07cf4f9fed7911fc2f6a90744cdde8b5df2a9d17

this warantees that

the revision id is unique

each revision also has a

local "revision number"

which is NOT unique

as you work you modify, add or remove files

after you commit,

hg status shows that there are no changes

commit is a local operation,

revisions are not visible to

anybody else until you share them

this creates what is called an

"anonymous branch", which is

a new "branch" on the revision tree

or DAG

This is just a fancy name

for a graph in which a node

cannot be linked to an ancestor node

creating a new branch also creates a new "head"

the merge is performed by combining the changes of each revision to their common ancestor

if there are no conflicts

the merge is trivial

if there are conflicts they must be resolved

merging DOES NOT create a new revision

hg commit

all these operations are "local"

they don't require access to a server

they don't require network access

they are fast!

this makes mercurial

ideal for personal projects

and solo work

• hg clone
• hg pull
• hg push

TortoiseHg is a GUI on top of mercurial

• it is cross-platform (Windows, Unix and Mac)
• it offers a workbench and an explorer/nautilus/finder interface
• it shares very little code with TortoiseSVN (mostly just the name and some icons)

you can clone a clone, etc

the new revision has a

unique hash, and

its revision number is 2

the new revision also has

revision number 2, although

its contents are different to

those of the revision number 2

in the cloned repository

however, the revision hashes

are different

note how revisions #2 and #3 refer

to different revisions in both repositories

what is revision number 2 in the source

repository, becomes revision number 3

in this repository

the revision hashes remain unchanged

revisions are given revision numbers

according to the order in which they are

"added" to the repo

pulling does not change the current revision,

nor the working directory on the target repository

thus, pull is "safe" and can be run at any time without risk

however, it is advisable to run hg incoming first,

to check what you will pull into your repository

looks for the revisions that are

in your local repo but are NOT

on the remote repo

sends those revisions to the remote repo

hg push fails if any branch

has more than one head

you can use --force

to push anyway

the target repository

must already exist

the "remote" repository

may be on the local machine

it does not change

the current revision

or the working directory

on the target repository

pushing does NOT change the current revision

nor the working directory contents on the

target repository

pull-merge-push is a common pattern

you may need to repeat this process

multiple times if there are other

developers pushing to the same repo

a way to avoid this problem is to not push often

only push when you have finished working on a feature

original repo

hg push

"pushes" revisions

from a local repostitory

to a remote repository

hg outgoing

user B commits the merge and

pushes its changes

is the "dry run" version

of hg push

merging does NOT create a new commit

merge does not modify the repository history,

just the working directory

user B must merge

the two heads before pushing,

resolving any conflicts that are found

user B tries to push to the original repo,

but fails because it would create new heads

user B pulls from the original repo

hg pull

"pulls" revisions

from a "remote" repository

into a local repository

hg incoming

is the "dry run" version

of hg pull

original repo

user B commits a new revision

user A also commits a new revision

in parallel in the original repo

cloned repo

hg clone

creates a copy of an existing repository

the existing repository may be local

or remote

TortoiseHg

toolbars

revision list

can be understood as a combination

of several other mercurial commands:

Repository

"Registry"

revision

details

file list

current file

contents

create a new target repository (hg init)

pull the revisions from to the source repository (hg pull)

update the target repository to the tip of the default branch (hg update)

original repo

working with others

fixing mistakes and editing history

extending mercurial

sharing your repositories

to collaborate with others

you must be able to share your work, (i.e. your revisions) with them

hooks

the simplest way to share your work is to

share the folder containing your repo

history in mercurial is additive and immutable by default

hooks are actions that are automatically triggered whenever something happens (on commit, on update, on tag, on pull, on push, etc)

mercurial has 3 main commands

to share revisions:

for extra performance and safety, you can also a mercurial web server

hg backout

create an "inverse commit" that undoes an existing revision

you can configure mercurial to execute one or more actions (python or shell scripts) whenever a hook is triggered

There are 2 ways to run a mercurial web server

it is possible to edit history by using the mq extension

start a simple, single threaded web server

hg serve

you should only edit non shared history

extensions

use it when you want to quickly share one

or more of your repositories

hgweb.py

it is quite easy to create mercurial "extensions" which can modify and extend most mercurial commands or even add new commands

a builtin python based script that

can be run as a WSGI or CGI script

under Apache, IIS or any other

stand alone web server

recent mercurial versions keep track of which revisions have been shared (pulled or pushed)

this is called mercurial phases:

• secret
• draft
• public

committing a merge

reduces the number of heads by one

you must commit for that

extensions are written in Python

It is also possible to share repositories via SSH and to send patches by email

hg merge

many extensions are bundled with mercurial

merges the contents of two revisions,

which become the working directory "parents"

hg branch

creates a new "named branch"

the default branch name is "default" :-)

branch names are immutable

and set in stone when you commit

the branch name is part

of the commit meta-data

hg commit

you can commit even if you are not at the "tip" of the repository

each extreme of each

"branch" is called a "head"

DAG means

Directed

Acyclic

Graph

hg commit

usual workflows

some advice

other stuff

hg update

lets you "go"

to any revision

updating to a revision

changes the "current revision",

which changes the files in the

"working directory" so that they match their states when that revision was committed

hg commit

most people setup a central server to share all their repositories, but they may use temporary servers to share revisions between coworkers

each commit creates a new revision with its own unique id

• commit often (its cheap and fast!)
• write good commit messages
• pull often (so that you can see what others are doing
• merge as needed (to keep your branches up to date)
• push sparingly, when you feel your work is ready to be shared

hg status

shows files as:

• modified (M)
• added (A)
• removed (R)
• missing (!)
• or unknown (?)

shows the difference between the

"working directory" and the "current revision"

creates a new,

empty repository

hg add

• some useful extensions
• mq, rebase,
• largefiles,
• convert, hggit, hgsubversion,
• eol, acl, projrc
• tags and bookmarks
• subrepositories
• when something goes wrong
• hg verify, hg recover

hg commit

creates a new "revision"

developers clone the repositories from the central server, create new commits and pull/push as needed

you MUST provide a

commit message

it is common to create per feature branches