3. 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.
4. 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
10. Short Tutorials
Starting a new project locally
just for you in your home dir.
11. 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
12. Starting a new project locally
• For you only, in your home directory:
13. Starting a new project locally
• Creating a new repo: Easy as pie
In this slide
cd Projects
hg init My_New_Project
14. Example
Starting a new project locally
situation
/home/staff/irmak/
Projects/My_New_Project/
Source: http://www.hginit.com
15. Short Tutorials
Simple local workflow
What you will do most with your own Mercurial
repo
16. 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)
17. 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
24. Short Tutorials
Starting a new lab project
A central repo in /home/projects
for a lab project
25. 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
26. Starting a new lab project
• Let's say we want to create a repo in /home/projects/Social
• which can be accessed by any member of the social group.
27. Starting a new lab project
• 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
28. Starting a new lab project
• Check the permissions: user irmak has read/write
group social has only read permissions
In this slide
ls -ld Super_New_Project
29. Starting a new lab 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
30. Current
Starting a new lab project
situation
/home/projects/Social/
Super_New_Project/
Source: http://www.hginit.com
31. Short Tutorials
Checking out a lab project
you want your own working copy from a
central repo
32. 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://irmak@barcelona.chem-eng.northwestern.edu//home/projects/path/to/central/repo
You can switch “barcelona” with any workstation name.
33. Checking out a lab project
• Remember this?
• Let's check out a local repo clone of this central repo.
34. Checking out a lab project
• Let's go to our home dir.
In this slide
cd ~
35. Checking out a lab project
• Clone the repo.
• That's it. You have your own copy.
In this slide
cd Projects
hg clone /home/projects/Social/Super_New_Project/
36. Checking out a lab 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
37. Current
Checking out a lab project
situation
/home/projects/Social/
Super_New_Project/
/home/staff/irmak/
Projects/Super_New_Project/
Source: http://www.hginit.com
38. Short Tutorials
Workflow with a central repo
What you will do most if you have a central
repo like a shared lab project
39. 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
40. 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)
41. Current
Workflow with a central repo
situation
/home/projects/Social/
Super_New_Project/
/home/staff/irmak/
Projects/Super_New_Project/
Source: http://www.hginit.com
42. Everyday changes in
Workflow with a central repo
local
• 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.
43. Everyday changes in
Workflow with a central repo
local
• It's empty. Let's change that.
In this slide
cd Projects/Super_New_Project
44. Everyday changes in
Workflow with a central repo
local
• Now there is a file in there.
In this slide
emacs new_stuff.txt
cat new_stuff.txt
45. Everyday changes in
Workflow with a central repo
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
46. Everyday changes in
Workflow with a central repo
local
• Change even more: The project progresses.
In this slide
emacs new_stuff.txt
cat new_stuff.txt
47. Everyday changes in
Workflow with a central repo
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
48. Pushing a new version
Workflow with a central repo
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
49. Pushing a new version
Workflow with a central repo
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
50. 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.
51. Current
Workflow with a central repo
situation
/home/projects/Social/
Super_New_Project/
/home/staff/irmak/
Projects/Super_New_Project/
Source: http://www.hginit.com
52. Working with multiple
Workflow with a central repo
local repos
• You go home. You want to work from home.
• Need another local clone of the central repo at home.
53. Working with multiple
Workflow with a central repo
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
54. Working with multiple
Workflow with a central repo
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
55. Working with multiple
Workflow with a central repo
local repos
• hg log shows all the history.
• You could go to any older version if you wanted.
In this slide
hg log
56. Current
Workflow with a central repo
situation
/home/projects/Social/
Super_New_Project/
/home/staff/irmak/
Projects/Super_New_Project/
In home laptop:
~/
Super_New_Project/
Source: http://www.hginit.com
57. Working with multiple
Workflow with a central repo
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'
58. Working with multiple
Workflow with a central repo
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
59. Working with multiple
Workflow with a central repo
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
60. Working with multiple
Workflow with a central repo
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
61. Working with multiple
Workflow with a central repo
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
62. Working with multiple
Workflow with a central repo
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
63. Working with multiple
Workflow with a central repo
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
64. Short Tutorials
Workflow with a central repo
c. Team Work
Working on the same project with multiple people
Changing different parts at the same time
Sharing these changes
65. Working with multiple
Workflow with a central repo
local repos
• 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.
66. Workflow with a central repo
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
Simple local workflow
in my in Andriana's
in my home
personal home dir.
dir.
• For sharing changes laptop
between people / computers,
follow Workflow with a
central repo
Source: http://www.hginit.com
67. Short Tutorials
Converting an svn repo to hg
Don't panic. Extremely simple.
68. 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)
69. Converting an svn repo to hg
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.
70. Converting an svn repo to hg
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 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)
71. 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
72. Converting an svn working copy
• 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
73. Converting an svn working copy
• 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
hg convert Hadoop-hCluster
74. Converting an svn working copy
• 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
75. Current
Converting an svn working copy
situation
/home/visitors/adampah/
Projects/Hadoop-hCluster-hg
Source: http://www.hginit.com
76. 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/
77. Converting a shared lab svn repo
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
78. Current
Converting a shared lab svn repo
situation
/home/projects/Systems-Biology
/Worm-Egg-Laying-hg
/home/staff/irmak/
Projects/Worm-Egg-Laying-hg
Source: http://www.hginit.com
79. 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.
80. Short Tutorials
Working together with svn
repositories
Mercurial understands svn
81. 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!
82. 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
83. Just accepting that it’s SVN
• First, you must create the main repository and the ‘nested’ repository
84. Just accepting that it’s SVN
• 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!
85. Short Tutorials
Advanced Topic:
Version control on large files
86. 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
87. 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
89. Creating a .hgignore
• 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!
92. 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
93. 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
94. 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
95. Checking out Snap
• To actually use this the first thing you have to do is check out Snap, it is
hosted on the internet
96. Checking out Snap
• To actually use this the first thing you have to do is check out Snap, it is
hosted on the internet
97. 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:
98. 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
99. 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
100. Short Tutorials
Resources
Where to look to get quick help
and to learn more
101. 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