Mercurial Tutorial

HgTutor

All Lessons

Short Tutorials

Setting up
1 minute,
Only once in your life

Setting up

Do this before everything

Edit the ﬁle ~/.hgrc (if it doesn't exist, create it)

Put these in:

[ui]
username= Your Name <your_email_adress.>

[extensions]
hgext.convert=
hgext.fetch=
{other extension stuff you want to enable}

Save it.

A config all to myself

•  Just like vi or emacs or bash, mercurial has a configuration file in your home
directory

•  You can edit this file at ~/.hgrc

•  You will need to set your username and e-mail in it
(Mercurial won’t work without it)

•  You can also enable new extensions in this file, such as hg fetch or hg
convert

Short Tutorials

Starting a new project locally
just for you in your home dir.


In short:

Wherever you want a new repo, do
hg init path/to/new/repo

Or to convert a regular directory into a hg repository:
cd path/to/that/directory
hg init


•  For you only, in your home directory:


•  Creating a new repo: Easy as pie

In this slide

cd Projects
hg init My_New_Project

Example
situation

/home/staff/irmak/
Projects/My_New_Project/

Source: http://www.hginit.com

Short Tutorials

Simple local workﬂow
What you will do most with your own Mercurial
repo

In short:
Make your changes.

hg status to see what ﬁles are different from last version

hg add to add all new ﬁles to the repo

hg commit -m “message” to commit changes without opening an editor

hg log to see history of changes (all versions)

More commands:
Make your changes.

hg status to see what files are different from last version
hg diff to see specifically what changes in each file

hg add to add all new files to the repo
hg add filename to just add specific files
hg remove filename to delete files (locally AND from repo)
hg forget filename to stop tracking changes on a file
hg addremove to add files, forget files you deleted, make everything sane.

hg commit to commit changes (opens an editor for a summary of changes)
hg commit -m “message” to commit changes without opening an editor

hg log to see history of changes (all versions)

hg update number to go back to that version
hg update to go to latest version
hg revert to go back to previous version


•  Remember this?


•  Say we created two ﬁles

In this slide

cd My_New_Project
ls
emacs new_file1
emacs new_file2
ls


•  Add the ﬁles to the repo, and commit the changes

In this slide

hg stat
hg add
hg commit -m “Testing”


•  Say we now changed something in a ﬁle

In this slide

emacs new_file1
hg stat

Simple workﬂow

•  Commit the changes

In this slide

hg commit -m “Changed some
wording”


•  Log shows the history of your changes

In this slide

hg log

Short Tutorials

Starting a new lab project
A central repo in /home/projects
for a lab project


In short:

Go to wherever the repo will be in /home/projects
hg init /home/projects/path/to/central/repo

If you need other people to contribute to it,
do the necessary permission changes, i.e.
chmod g+w /home/projects/path/to/central/repo


•  Let's say we want to create a repo in /home/projects/Social
•  which can be accessed by any member of the social group.


•  Oh my god it's so EASY
•  You're done if you don't need members of social to contribute

In this slide

cd /home/projects/Social
hg init Super_New_Project


•  Check the permissions: user irmak has read/write
group social has only read permissions

In this slide

ls -ld Super_New_Project


•  Easily remedied: Give the group write permissions
•  That's IT!

In this slide

chmod g+w Super_New_Project
ls -ld Super_New_Project

Current
situation

/home/projects/Social/
Super_New_Project/


Short Tutorials

Checking out a lab project
you want your own working copy from a
central repo


In short:

Go to wherever you want to have your local repo / working copy (those two are
the same thing in Mercurial)
hg clone /home/projects/path/to/central/repo

or if you want the local repo to be named differently,
hg clone /home/projects/path/to/central/repo path/to/new/local/repo

If you are not inside the ﬁlesystem (i.e. if you work from home)
hg clone ssh://barcelona//home/projects/path/to/central/repo
or
hg clone ssh://irmak@barcelona.chem-eng.northwestern.edu//home/projects/path/to/central/repo
You can switch “barcelona” with any workstation name.


•  Remember this?
•  Let's check out a local repo clone of this central repo.


•  Let's go to our home dir.

In this slide

cd ~


•  Clone the repo.
•  That's it. You have your own copy.

In this slide

cd Projects
hg clone /home/projects/Social/Super_New_Project/


•  As you can see, it's empty.
•  Nobody committed/pushed any changes yet: no log (no history)

In this slide

ls -ld Super_New_Project/
cd Super_New_Project
ls
hg log

Current
situation

Super_New_Project/

/home/staff/irmak/
Projects/Super_New_Project/


Short Tutorials

Workﬂow with a central repo
What you will do most if you have a central
repo like a shared lab project


In short:

Same as Simple Local Workﬂow,
hg commit to keep committing changes locally

When you have a good next version:
(hg outgoing shows what changes you will share with the central repo)
hg push to push to share changes with the central repo
If others changed the same ﬁles, you'll get a warning, pull and merge their
changes before pushing yours (see below for pull & merge)

To get the changes from other people:
(hg incoming shows what changes you will get from the central repo)
hg pull to pull other's changes from the central repo
hg merge to combine your changes with theirs (automatic, painless)
hg update to switch to working on this latest version you got

Short Tutorials

a. Everyday changes in local repo
What you do between having deﬁnitive versions
(Same as simple local workﬂow between pushes/pulls)

Current
situation

Super_New_Project/

/home/staff/irmak/


Everyday changes in
local

•  Go to your local repo

On this personal
repo, you follow the
same Simple Local
Workﬂow.
You commit your
changes, it keeps
track.
Central repo
doesn't know that
yet.

Everyday changes in
local

•  It's empty. Let's change that.

In this slide

cd Projects/Super_New_Project

Everyday changes in
local

•  Now there is a ﬁle in there.

In this slide

emacs new_stuff.txt
cat new_stuff.txt

Everyday changes in
local

•  Add & commit. This commit is still to your local repo.

In this slide

hg stat
hg add
hg commit -m “Plans about
Project”
hg log

Everyday changes in
local

•  Change even more: The project progresses.

In this slide

emacs new_stuff.txt
cat new_stuff.txt

Everyday changes in
local

•  Now we have OUR latest version.
•  Let's push all these changes to the central repo.

In this slide

hg stat
hg commit -m “Additional
plans”
hg log

Pushing a new version
to central

•  hg outgoing shows the changes we will be pushing.
•  In this case, it'll push both changesets (central doesn't have them)

In this slide

hg outgoing

Pushing a new version
to central

•  (We didn't need the hg outgoing step. That was just to check)
•  Ok, now do it. Push. The changes are now also in the central repo.

In this slide

hg push

Short Tutorials

b. Working with multiple local repos
When you want to work on your project from home or vacation, and keep
everything synched.

Working with multiple
local repos

•  You go home. You want to work from home.
•  Need another local clone of the central repo at home.

local repos

•  Imagine tunis is my home computer now please.
•  This is what I'd do on my home laptop.

Careful with the
double //

In this slide

hg clone ssh://irmak@istanbul.chem-eng.northwestern.edu//home/projects/Social/Super_New_Project/

ls

local repos

•  I just received the latest version.
•  The central had all the changes.

In this slide

cd Super_New_Project/
ls
cat new_stuff.txt

local repos

•  hg log shows all the history.
•  You could go to any older version if you wanted.

In this slide

hg log

Current
situation

Super_New_Project/

/home/staff/irmak/
In home laptop:
~/
Super_New_Project/


local repos

•  Working at home, you make progress.
•  You keep committing your changes (locally)

In this slide

emacs new_stuff.txt
hg stat
hg commit -m 'Fixed grammar,
added more stuff'

mv ../some_code.py .
emacs other_code.py
hg stat
hg add
hg commit -m 'Started coding'

local repos

•  You're done. Push these to central,
•  so you can get them when you're at work tomorrow.

In this slide

hg push

local repos

•  At work, you can pull all those changes and continue working.
•  Check what you'll be pulling with hg incoming

(Even if you forget to pull
and make other changes
on the repo at work, no
problem. You can pull &
merge later.)

In this slide

cd Projects/
cd Super_New_Project/
hg incoming

local repos

•  Do it, pull the changes you made at home.
•  This gets all the changes, but does not apply them yet.

In this slide

hg pull

local repos

•  hg log shows you the complete history you have now.
•  You see that you have the changes. BUT --

In this slide

hg log

local repos

•  hg summary tells you that on that history, this copy is at version 1.
•  (parent is where you're at now)

In this slide

hg summary

local repos

•  So you know about the latest version, you're not working with it yet.
•  hg update to switch to the latest version (3)

In this slide

hg update

Short Tutorials

c. Team Work
Working on the same project with multiple people
Changing different parts at the same time
Sharing these changes

local repos

•  During these pushes and pulls, we didn't need to merge.

•  Merging's needed if the same ﬁle is changed by different local repos,
at the same time, without central knowing about it yet.

•  Like when people are working on different parts of the same paper, for
example.

•  Hg will warn you about that, if you try to push a ﬁle that was changed by
someone else.

•  Then all you'll do is hg pull their changes, hg merge to combine your changes
with theirs, and then you can hg push normally.

•  Read http://hginit.com/02.html for a good and well explained example of a
team working on a repository together, including merges.

Team work

•  If Andriana cloned her own in /home/projects
local repo from the central,
we would have this picture

•  For each local repo, follow
in my in Andriana's
in my home
personal home dir.
dir.
•  For sharing changes laptop
between people / computers,
follow Workﬂow with a
central repo


Short Tutorials

Converting an svn repo to hg

Don't panic. Extremely simple.

In short:

To create a separate Mercurial repo from an svn repo
hg convert /path/to/svn/repo

That's it.
Your svn repo will be left unchanged.

A new hg repo will emerge.
(and it will know everything that svn knew)

If the svn repo was called “ProjectName”, the new hg repo will be a new directory called
“ProjectName-hg”
(you can specify a different name if you want)

In short:

To create a separate Mercurial repo from an svn repo
hg convert /path/to/svn/repo

You can do this:
- to a local svn working copy
- to the actual place where the svn repository resides

Either way works.
There are no real differences between resulting hg repos.
Choose the more convenient one according to your needs.

In short:

Converting your svn working copy:
hg convert ~/Projects/CommunitiesSA
You'll get a repo right there, you'll probably use that locally
(Simple local workﬂow)

Converting the actual svn repository:
hg convert /home/projects/Networks/CommunitiesSA
That's probably what you'll do with lab projects to get a central hg repo, then you'll
clone local hg repos to your home dir., other places, other peoples homes, etc.
(wherever needed)
(Workﬂow with a central repo)

Converting an svn working copy

Example workﬂow

to get an hg repo (for local use purposes)

from an svn working copy

Example svn working copy:
/home/visitors/adampah/Projects/Hadoop-hCluster


•  Let's convert a working
copy.

•  Go to where your working
copies of svn repos are.

•  Hmm. I say we convert this
Hadoop-hCluster

In this slide

cd Projects
ls -l

•  Apply the convert command.

•  You can see it processing
every version in the svn repo

•  This creates
Hadoop-hCluster-hg here.

•  It's an hg repo with all the
ﬁles and version history of
Hadoop-hCluster

In this slide

hg convert Hadoop-hCluster


•  You can check if you
really have all the version
history with an hg log

•  It's all there!

•  The changes are all there,
but don't forget hg
update
to apply them and switch to
the latest version.

In this slide

cd Hadoop-hCluster-hg
hg log

Current
situation

/home/visitors/adampah/
Projects/Hadoop-hCluster-hg


Converting a shared lab svn repo

Example workﬂow

to get a central hg repo setup

from an svn repo

Example svn repository:
ﬁle:///home/projects/Systems-Biology/Worm-Egg-Laying/


Go to the parent directory of svn repo.
cd /home/projects/Systems-Biology/

Convert the repo.
hg convert Worm-Egg-Laying

Check permissions.
ls -ld Worm-Egg-Laying

Give necessary permissions.
chmod g+w Worm-Egg-Laying

Central repo ready. Go home to get a local repo there.
cd ~

Go to where you want to have your local repo.
cd Projects

Clone the central repo.
hg clone /home/projects/Systems-Biology/Worm-Egg-Laying-hg

Current
situation

/home/projects/Systems-Biology
/Worm-Egg-Laying-hg

/home/staff/irmak/
Projects/Worm-Egg-Laying-hg


Final Notes:

If you convert an svn repository with a trunk/tags/branches structure,
hg convert will automatically handle all of it –
if you were only using trunk, your hg repo will have what trunk had.

hg convert gets all the versions, but doesn't apply them to the new directory.
You should do hg update to switch to the last version if you want to work in it.
But if you will hg clone another repo from this (i.e. to get your own local repo), that's ﬁne.
The cloning will update your new clone automatically.

Short Tutorials

Working together with svn
repositories
Mercurial understands svn

Working on top of an SVN repository

•  What if you have to have an SVN repository that you are actively working on?

•  There is an extension that can help you work with this, it is called
hg-subversion

•  This extension allows you to work in Mercurial commands, that are then
translated to SVN commands

•  To check out a project nose to use with hg subversion you would do:

•  After that you can work as normal

•  A word of warning though, this is still an extremely active coding project and it
may change or break at any time.

•  Don’t rely on this to work with all of your repos!

Just accepting that it’s SVN

•  There are some projects where neither of those things make sense, such as
•  Ones that have to stay as SVN for legacy reasons
•  But aren’t actively used enough to do anything special for
•  Like JabRef

•  Fortunately Mercurial supports subrepositories

•  These subrepositories can be Mercurial repos or SVN repos


•  First, you must create the main repository and the ‘nested’ repository


•  Next, tell it where the path is and put it into the .hgsub ﬁle

•  Now you can just continue to use svn commands with this subrepo

•  Or you can use hg-subversion with it

•  It’s up to you!

Short Tutorials

Advanced Topic:
Version control on large ﬁles

An introduction to Mercurial and big files

•  So first, let’s clear up what are big files.

•  Mercurial by default warns you about any file over 10 MB.

•  You might worry about this but don’t! It works with that file anyway

•  It warns you because extremely large files cause a clone over the internet to
go really slow (of course, there’s no way around this. 1 GB is 1GB no matter
what)

•  Mercurial is designed for this decentralized type of collaboration so it warns
you to make you think whether you really need that file in there or not

•  Sometimes you do need that file and sometimes you don’t, so let’s evaluate
these situations

I don’t need that big stinking file!

•  Our filesystem is (or should) be backed up

•  So if you have a large file (hundreds of megabytes) that is not going through
versions i.e. it just sits there it doesn’t necessarily need to be in version
control

•  This is especially true when you don’t actually share your repository with
anyone.

•  There is a simple way you can do this, you can create a .hgignore file

•  This file tells Mercurial what to ignore

Creating a .hgignore

•  First, create the ﬁle


•  Next, set it up and then tell it what to ignore
•  It can be speciﬁc ﬁle names or regular expressions, but be careful with
regexes!


•  Then just add and commit the .hgignore ﬁle

Okay, I actually need these large ﬁles

•  So these ﬁles are large and constantly changing, I need to keep track of them

•  You could continue to have Mercurial track them, but it’s not the best solution

•  There are multiple extensions that have been created to solve this problem

•  You can choose from Big Files, bFiles, or Snap

•  Snap is what has been chosen as the lab standard, it’s the simplest/most self
contained

•  You can pick whichever one you want though and pursue it

•  All of these are under heavy development and are constantly changing

•  However, they all have the same basic idea

How do these extensions actually work?

•  The way that these extensions work is fairly simple

•  What they do is for any file above a given size, they take it out of Mercurial’s
control and put it into theirs

•  So when these files are committed or changed what they do is make a tar file
of that file and commit it to its own repository

•  This zipped file has a MD5 hash that is used as an identifier

•  A string that incorporates the file name and the MD5 hash is then placed in a
file that Mercurial keeps track of

•  This way Mercurial versions just the strings itself, which are fairly small

How do these extensions actually work?

•  When the file changes, instead of keeping diffs of it (which would be really
large) it just creates a new zip of the file with a new MD5 sum

•  You can still diff between the different versions of the file but the extension
handles the diff’ing

Checking out Snap

•  To actually use this the ﬁrst thing you have to do is check out Snap, it is
hosted on the internet

Setting up Snap

•  Next you have to determine if you want snap to be global or project specific
•  If it is global then you need to configure your .hgrc
•  If it is project specific then you should modify the .hgrc file in the .hg directory
of the project
•  Your .hgrc file should now look something like this:

Setting up Snap

•  The ‘hgext.snap’ line tells Mercurial where snap is and activates the extension
•  The ‘[snap]’ section configures special things about snap and is not
necessary
•  ‘size_threshold’ tells it the file size at which it should start working, mine is set
for 750 MB
•  ‘patterns’ tells it what regex patterns it should act on regardless of the file size
•  If these two aren’t configured then it will work on any file over 10 MB by
default

Using Snap

•  Once you have Snap set up it will automagically work

•  You can tell that it is working because after a ‘hg add’ and ‘hg commit’ it will
tell you how many files were added to a repository and of those how many
were snap files

•  A fair warning though, this will slow down mercurial

•  This is because it is tracking all those files for changes and checking MD5
sums

•  It is faster than just having Mercurial do it, but you will still suffer a slowdown

Short Tutorials

Resources
Where to look to get quick help
and to learn more

Resources

•  http://hginit.com/
•  Good explanation of concepts
•  Great examples for almost anything you'll need to do
•  Pictures, screenshots, diagrams: very clear
•  Easy to read, humorous, not too long
•  Very helpful resource, highly recommended to read once

•  http://mercurial.selenic.com/guide
•  Ofﬁcial guide
•  Very short, to the point, like a collection of cheatsheets
•  Organized in workﬂows
•  What you need to do in which order for every use case
•  Not for digesting the concepts
•  Ideal for quickly checking how to do something

Mercurial Tutorial

More Related Content

What's hot (12)

Similar to Mercurial Tutorial (20)

More from Adam Pah (7)

Recently uploaded (20)

Mercurial Tutorial