

Hg Init: a Mercurial tutorial by Joel Spolsky - Tichy
http://hginit.com/

======
matrix
If this is advertising, I want more of it. As an SVN curmudgeon, the first
part of this tutorial finally persuaded me that I really, really need to give
distributed version control a fair trial. Joel pretty much nailed all my
objections/complaints/whines about switching. But I also know the pain of
merging all too well - a benefit that I hadn't really seen explained as
persuasively before.

~~~
ezy
This I don't get. The branching/merging thing seems to be overblown to me.

The reason I'm switching is because I like the tools better, and you can be up
and running with a repo in about 5 seconds. I think that's argument enough.
There's less pain.

But what is so different about merging in hg/git that merging a complex change
from a branch is somehow made magically trivial? I mean, the tools for
handling changes might be better because they are more modern, but the whole
"changeset" thing seems to be hyperbole -- _all_ (well, any good one) VCS's
track changesets, that's what those revision numbers (or collectison of rev
numbers) mean. :-)

~~~
InclinedPlane
The difference is that SVN is dumb on a profound level when it comes to
diffing. It knows how to diff one file vs. another, and that works great for
incremental changes all in one branch, but it doesn't keep track of revision
and merge history the way more modern tools like perforce, TFS, and especially
git and mercurial do.

The end result is that when you have two branches that have become even a
little out of sync with each other when you try to merge them together SVN
doesn't know what to do because all it can do is diff one version against the
other. Imagine how this looks if you've spent a bunch of time refactoring in
one branch, moving code around, deleting code, adding new code, etc. The end
result is that you basically have to hand-edit each file into the final merge
state you need it to be in, entirely defeating the very reason you use source
control tooling in the first place. You might as well just print out all the
code from each branch and get a committee to merge it all together using
scissors and craft glue, it wouldn't take any longer or be any more onerous
than it would be using SVN.

In contrast, more sophisticated VCSes, including hg, keep track of changesets,
and they are capable of tracking those changesets as they move through
different branches. When you merge in Mercurial it's able to trace through the
revision history of a file in the source and target branches, find the common
revision, then separately apply the diffs from the source and target branches,
automatically check for conflicts (e.g. changes from both sides that touch the
same blocks of code) and create a sanely merged final result which will only
be flagged as a merge conflict requiring manual intervention when there's a
high probability that there actually is a merge conflict. More so, the merge
conflict will be presented in such a way that it's actually sensible, showing
the actual conflicting changes and the resulting conflicting final versions of
the file, making it fairly straightforward to resolve even in that case.

Casting this in the form of a real world example, consider a "main" branch
with two dev. teams each working in their own child branches. For the most
part each dev. team works on their own code within their own set of files,
separate from the other team's, but there is some common code which both teams
have a tendency to contribute to or change. Team A spends a bunch of time
making changes in their own branch (branch A), committing as they go, then
merges these changes up to main. Later team B merges their changes to main as
well. Instead of running into a merge conflict nightmare that requires huge
amounts of developer time be expended in sorting out the state of each and
every file, the version control system sees that team B hasn't made any
changes to most of the files in the repository, and most of the changes team B
has made are to files that haven't been changed by anyone else, and there are
only a tiny number of changes to files that had also been changed by team A's
recent commits, which hadn't been merged to team B's branch before team A
pushed their code up to main. However, most of those edits are to distinctly
different parts of the shared files, and are automatically merged without
human intervention, only a tiny handful of merges require manual intervention,
a process that takes only a tiny number of people a few minutes to sort out.
Some of those automated merges may, in theory, not be safe, but that is what
testing is for, and the devs can still review and sanity check the merged
files before committing if they like.

The ability to turn a show-stopping ordeal into a routine task can be utterly
transformative to the development process. There are many big dev. shops that
are reliant on dozens or perhaps hundreds of big merges (in multi-thousand
file code bases) shuffling around code between various branches every day.

~~~
aaronkaplan
_When you merge in Mercurial it's able to trace through the revision history
of a file in the source and target branches, find the common revision, then
separately apply the diffs from the source and target branches..._

Originally subversion couldn't do this, but it has had merge tracking since
version 1.5 (a couple of years already). You can now merge one branch into
another multiple times without specifying explicitly which revisions to
compare.

I have seen a number of people saying that the merge tracking in subversion
still isn't as good as what's in git or mercurial, but I haven't found an
explanation of the difference. Can someone elaborate, or point me to some good
reading?

lallysingh and nollidge point out that in a DVCS model you tend to make more
frequent commits, because committing and publishing are no longer the same
action, and that having finer-grained commits makes automatic merging more
likely to succeed. This seems quite plausible to me, but it's orthogonal to
the problem of merge tracking (isn't it?).

------
solutionyogi
Now that's what I call organic SEO effort for their product Klin. I think
patio11 will approve! :)

EDIT: The above comment may seem negative but that's not the intention. As
much as this site will help their SEO effort, I think the guide itself is
awesome. I am a git user and when I was learning git, I went through similar
'examples' to understand git. I think this is the best way to learn git or hg!

EDIT: I wanted to mimic the guide for git at gitinit.com and someone has
already registered it!

~~~
patio11
I have this funny feeling that Joel Spolsky probably does not need to read my
blog for advice on effective software marketing. But yes, I approve. Do stuff
like this. It works, it is inexpensive, it lasts forever, and your customers
will love you for it.

(Though if you're doing it for narrow SEO reasons, I might consider not
breaking it into its own domain. Links pointing at it won't help the product
rank if the product is on a domain different than the linkbait.)

------
mattchew
Proof that Joel still has something to offer developers besides "if you were
any good you'd be on StackOverflow right now". <g>

As it happens I started moving to Mercurial _yesterday_ , how is that for
luck. I think the Hg site documentation is fine, but I have to say, Joel's is
more fun right out the gate. May much Google juice flow his way.

------
jasonkester
I always enjoy reading Joel's writing, regardless of whether I happen to agree
with whatever he's saying. He can take on a subject as dry as comparing two
version control systems, and make it enjoyable to read. Especially when he's
working without an editor (his inc. stuff reads like it has been edited out of
all recognizable shape.)

Compare it to the normal dry, unreadable technical writing on similar subjects
and it's just night and day.

------
alanb
For those of you comparing git and hg, I would suggest that they are actually
quite similar. Check out this article "Mercurial for Git Users" here:

<http://mercurial.selenic.com/wiki/GitConcepts>

It answered many of my questions on the nuances of Mercurial. The branch
model, bare repositories, and command equivalence table were especially
helpful for someone like myself who has used both systems but never fully
understood the distinctions.

------
sumeeta
I like that Joel decides to say "OK, forget about Subversion or whatever you
know about source control in general. I'm going to teach you about the DVCS
way from the ground up." It's great that he treats this guide like an
introduction to the concept of version control, but I think you really need
experience with VCS before you can understand Hg Init.

Is there an easy way to educate older and/or less technical IT professionals
about source control? I haven't been able to do it myself, and I wish this was
it.

~~~
weaksauce
This looks good from an overall why you should learn it point of view and also
to help you with the lingo that you should know:

[http://betterexplained.com/articles/a-visual-guide-to-
versio...](http://betterexplained.com/articles/a-visual-guide-to-version-
control/)

For IT people you should have your /etc/* files under revision control to
track any changes and easily roll back changes that break your system. I
actually think there are some tools that are specifically for this purpose and
not the general purpose SVN/git/hg variety but I cannot think of them off the
top of my head.

~~~
carey
You're probably thinking of etckeeper:
<http://joey.kitenet.net/code/etckeeper/>

------
MikeMacMan
Nice use of Balsamiq Markups in the diagrams, by the way.

------
Estragon
That was great. What does Kiln get you that Mercurial doesn't?

~~~
jasonrr
Kiln gets you a pretty cool (if I do say so myself) code review system, an
all-new web interface for managing your code and repositories, tight
integration with FogBugz, and support from Fog Creek. If you don't need those
things, then by all means, use the open source version.

There's a free trial of the hosted version that you can sign up for at
<http://www.kilnhg.com/>. Also, Kiln and FogBugz are both free for Students
and Startups (2 users or less). Give it a shot and let us know what you think.

~~~
MartinCron
As a kiln user, I'll back up Jason's statements here. Working with it day-to-
day, it's not really any different from using the open source version of hg,
but the web UI and code reviews are pretty damn cool.

------
jimbokun
Would any of this transfer to understanding how git works as well?
Alternatively, is there a similar introduction to git? I'm in the camp of
someone who has used CVS and Subversion a lot and have had "learn Git" or some
other distributed VCS on my to do list for a while now.

~~~
josephruscio
Scott Chacon has a couple excellent resources: <http://progit.org/book/> and
<http://whygitisbetterthanx.com/>

~~~
sreque
<http://whygitisbetterthanx.com/> doesn't represent mercurial 100 percent
accurately.

Cheap local branching: mercurial has had this since day one, and for a long
time has had most of the capabilities mentioned in this section for a while.
Unfortunately, it hasn't had good named branching support, so most mercurial
users preferred to branch through cloning, but that was never necessary. Right
now you can use bookmarks for temporary named branches but there's no built-in
support for sharing them. You have to write your own extensions to copy
bookmarks files around automatically or just do it manually. Mercurial really
needs to deal with this, I think. It's the only feature I've seen in git that
I wish mercurial had.

Staging area: mercurial has mq, which is far more powerful than a staging
area. In all honesty, I only use mq as a staging area and ignore it's other
features most of the time, and using mq only as a staging area is just as easy
as using git's staging area. Also, not having a staging area forced on the
user by default makes mercurial much easier to pick up than git initially, and
later on if a user wants the same functionality he or she can get it.

github: Mercurial has bitbucket. Github is far more popular, but not
necessarily technically superior as far as I know.

That puts mercurial almost entirely on par with git in terms of this web
site's criteria.

edit: reading more carefully, <http://whygitisbetterthanx.com/> doesn't
actually claim mercurial doesn't have the features mentioned above. It does
just claim that git does things better. They say their local branching is
better(it is) and github's social atmosphere is better than competing
products(it is). However, with mq and the record extension you can do the same
things as with the staging area.

~~~
grayrest
Since we're discussing this, is there any equivalent to git rebase
--interactive?

Coming from darcs to git (I add -p more or less exclusively), I didn't think
I'd use rebase much but commit reordering/squashing has turned out to be very
useful the few times I've wanted it. I know it's doable with mq, but you have
to know to mq everything before the fact rather than after.

~~~
bcully
That'd be the histedit extension, I believe.

------
Luyt
Did someone also notice Kiln has a Dodo as logo? That bird went extinct in the
late 17-th century (<http://en.wikipedia.org/wiki/Dodo>). I wonder what the
meaning of this is. Maybe a pun on 'the way of the dodo', a place where your
source code certainly _won't_ go, if you use Mercurial.

~~~
gecko
We were looking for a good mascot for Kiln, but unfortunately, all of the
animals that we consulted were already in exclusive contracts with other
products except for _Strigiphilus garylarsoni_ and the inverted flame-weasel,
neither of which we felt represented our product well.

Late one night in the Kiln alpha period, though, I was hacking around the
Mercurial integration, messed up, and suddenly realized that issuing "hg up"
held the repository at its current version, but moved time itself to match the
requested revision. In other words, I had unintentionally made a time machine
out of Mercurial. After riding a dinosaur for awhile, it hit me that I
suddenly had a chance to get Kiln a legitimate mascot.

I thought for awhile about where and when to go, then promptly "hg up"d to the
mid 1600s. I went to the island of Mauritius, and approached the dodo bird. I
explained that, through no fault of the poor bird, it was about to go extinct.
But I had an option: I could "hg revert" the thing back into the present,
restoring it from extinction, if only it'd be willing to sign an exclusive
marketing contract for Kiln. We negotiated a little bit back and forth, but at
the end of the day, as you can see, the dodo happily agreed. It now lives a
life of luxury, and has even taken up recently to hanging around kiwi birds an
awful lot.

Unfortunately, the current version of Kiln can only restore deleted files, not
deleted species, but we still think the dodo--a peaceful bird with no natural
enemies, restored to the present--makes a nice mascot.

------
Splines
Not having used Hg much at all (just a few hg commits and an hg clone), could
it be used on top of a non-distributed source control system like SVN?

E.g., take advantage of hg commit and related commands to try changes out on
the local repository, and use svn to commit those changes to the central
repository?

~~~
iamelgringo
You shouldn't have much problem with that. You'd just have to make svn ignore
the .hg folder in your local repository, and you can use hg locally for
whatever you want, and when you're at a point that you want to push your
changes to your svn central repository, you can.

------
ams6110
OK I just finished the first block (Subversion Reeducation) and one of the
main points he makes is _In Mercurial, every developer has their own
repository, living on their desktop_

But if you read the subversion book, or any other good tutorials, you know
that developers using svn can just as well make their own private branches

So under branches/ I can have bob/ sue/ alice/ and they can have copies of
trunk (or other branches) to their hearts content.

So why is this a big "win" for Mercurial?

(Will read the other sections later, no time now)

~~~
anthonyb
It's a win for DVCS in general, not just Hg. A couple of use cases off the top
of my head:

* I can take my repository on the train/bus/wherever and still commit.

* If I'm working with someone who needs to use my 'buggy' code I can push just to their repository (or they can pull from mine).

* I can have my own workflow and create as many branches, checkouts, etc. as I need.

Of course, the example that he gives there is bizarre - effectively the Hg
equivalent of hanging onto your code for 6 weeks and then merging all at
once...

~~~
nkassis
2 and 3 are easily done in SVN also. 2 is basically merging your changes in
personal branch to the personal branch of another user. 3. Well your branch in
SVN is your domain, do what you want.

I think the main advantage is really for larger groups. Having 3000 branches
in the linux repo would be unmanageable. Also, private branches are something
SVN can't do to my knowledge. If I want to hack on a git repo without anyone
knowing, it's easy.

But there's many advantages to GIT/Mercurial over SVN/* aside from the
"everyone has a repo". I love git but currently use SVN due to legacy and
keyword expansion at work and it's not that bad.

------
Vitaly
I've just finished the introduction part and there is one thing he got wrong.
the changesets vs revisions thing. Changesets and revisions are completely
equivalent as far as merging is concerned (and almost anything else) because
one is trivially computed from the other. and git which has even better
merging support tracks file contents not diffs, which is another proof that
this argument is irrelevant.

~~~
inaequitas
If you speak of Mercurial's changesets and revisions, they are clearly not
trivially computed from one another, being that a revision is clone-specific,
and a changeset is a hash computed on a single file by looking at all it's
ancestors' states. REPO1 and REPO2 can both have 5 revisions and only one is
common to both — a merge is possible, but the changesets considered will be
_very_ different.

If you're comparing SVN's revisions with Hg's changesets, still no dice, for
the same reason: changesets are unique for a file, given that file's history,
and the hash trail allows for a clear way to figure out where changes
happened, and merge from that point. A SVN revision just tells you how many
commits have happened up to that point.

------
icco
I'm generally not a big fan of Spolsky's writing. He tends to read too much
like a sales person, and too little like an engineer for me to enjoy his
writing.

This is a great read though, even if you already switched to git, because the
two are so similar.

------
Lorin
Although I wouldn't be using mercurial myself, I gave this a point simply
because of the great site design and layout.

------
callmeed
I still can't get HG to build with MacPorts/SnowLeopard ... seems to be a
problem with Python.

~~~
brodie
Have you tried the binary installer? <http://mercurial.selenic.com/downloads/>

If you're intent on building from source, make sure you're running "sudo
python setup.py install; sudo make install-doc". Installing with the makefile
directly will place packages in /usr/local, where Python doesn't normally live
under OS X.

~~~
ubernostrum
Or if you're serious about installing Python packages, you already have a
.pydistutils.cfg file specifying where you want things to install. Learning a
few options to put in that file is a lifesaver.

------
iamelgringo
Great writing Joel. Thanks.

------
cbetz
I find the choice of characters and the paragraph descriptions of them a
little strange. I get the point that it helps the story to make up a whole
life story for each member of the hypothetical development team. What I don't
understand is why each team member is portrayed in such a negative light. Are
your co-workers that bad?

------
freetard
Note that the only reason Spolsky is doing this is because he bet on Mercurial
a few years ago for his project <http://www.fogcreek.com/Kiln/> which is
Mercurial only. Unfortunately for him, git got more popular than hg so now
he's promoting hg as much as possible.

~~~
Quiark
Or maybe they don't want to risk a program that isn't 100% Windows compatible,
because lots of their potential customers use Windows.

~~~
jrockway
As a hardcore UNIX/git user, I've found the Windows git tools to be more than
adequate.

~~~
tghw
If only Windows users were hardcore UNIX users...everything would be so much
easier. No GUI code, no leaking GDI objects, no Java Swing, no WxWidgets, no
cross-browser bugs (curl would be the only browser), no DPI scaling issues, no
DLL hell, and no IE. Just text. Beautiful, green text. And it would all be BSD
licensed.

Oh, what a wonderful world that would be...

