Mercurial Tutorial

HgTutor

All Lessons

Short Tutorials

Setting up 1 minute,

Only once in your life

Setting up

Do this before everything

Edit the file ~/.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

Only once in your life

Short Tutorials

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

Starting a new project locally

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


Source: http://www.hginit.com

Example situation

/home/staff/irmak/ Projects/My_New_Project/

Short Tutorials

Simple local workflow What you will do most with your own Mercurial

repo

Simple local workflow In short: Make your changes.

hg status to see what files are different from last version

hg add to add all new files to the repo

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

hg log to see history of changes (all versions)

Simple local workflow 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

Simple local workflow

• Remember this?


• Say we created two files

In this slide

cd My_New_Project ls emacs new_file1 emacs new_file2 ls


• Add the files 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 file

In this slide

emacs new_file1 hg stat

Simple workflow

• 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

Starting a new 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

Checking out a lab project

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 filesystem (i.e. if you work from home) hg clone ssh://barcelona//home/projects/path/to/central/repo or hg clone ssh://[email protected]//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


/home/staff/irmak/ Projects/Super_New_Project/

Short Tutorials

Workflow with a central repo What you will do most if you have a central

repo like a shared lab project

Workflow with a central repo

In short:

Same as Simple Local Workflow, 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 files, 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

Workflow with a central repo a. Everyday changes in local repo

What you do between having definitive versions (Same as simple local workflow between pushes/pulls)



Current situation




• Go to your local repo

On this personal repo, you follow the same Simple Local Workflow. 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


• Now there is a file in there.


In this slide

emacs new_stuff.txt cat new_stuff.txt


• 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


• Change even more: The project progresses.


In this slide

emacs new_stuff.txt cat new_stuff.txt


• 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


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

Pushing a new version to central

In this slide

hg outgoing


•  (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.

Pushing a new version to central

In this slide

hg push

Short Tutorials

Workflow with a central repo b. Working with multiple local repos

When you want to work on your project from home or vacation, and keep everything synched.



Current situation




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

Working with multiple 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://[email protected]//home/projects/Social/Super_New_Project/

ls


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


In this slide

cd Super_New_Project/ ls cat new_stuff.txt


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


In this slide

hg log



Current situation


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

~/ Super_New_Project/


• 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'


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


In this slide

hg push


• 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


• 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


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


In this slide

hg log


• 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


• 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


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

• Merging's needed if the same file 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 file 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

in my personal laptop

in my home dir.

in /home/projects

in Andriana's home dir.

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

• For each local repo, follow Simple local workflow

• For sharing changes between people / computers, follow Workflow with a central repo

Short Tutorials

Converting an svn repo to hg

Don't panic. Extremely simple.

Converting an svn repo to hg 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)


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.


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

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) (Workflow with a central repo)

Converting an svn working copy

Example workflow

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


In this slide

hg convert Hadoop-hCluster

• 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 files and version history of

Hadoop-hCluster


In this slide

cd Hadoop-hCluster-hg hg log

• 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.



Current situation

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

Converting a shared lab svn repo

Example workflow

to get a central hg repo setup

from an svn repo

Example svn repository: file:///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

Converting an svn repo to 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 fine. 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 file

• 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 files

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 file


• Next, set it up and then tell it what to ignore •  It can be specific file names or regular expressions, but be careful with

regexes!


• Then just add and commit the .hgignore file

Okay, I actually need these large files

• So these files 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 first 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 • Official guide • Very short, to the point, like a collection of cheatsheets • Organized in workflows • 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

Technology

Transcript of Mercurial Tutorial