So if you’ve read the Server Setup tutorials, you’ve heard me mention “version control.” Version control has typically been called a “time machine” to look at your code. What that means is you can look at your code at any moment time as it has been developed. You can do things like revert back in time to what your code looked like at a previous point in time, i.e. “roll back” your code to how it was last week. Or, just look at what your code was a while ago before you altered it. It serves the purpose of giving you confidence to do things like delete and replace old code with new and better solutions. So in the case that the new code isn’t quite right, you can go back and look at how it was before. It also greatly aids multi-developer teams. It allows each developer to work with an unchanging set of code. So that means if another developer changes something, it won’t break your code. However, there will be a time when you have to merge your code with the code of other developers. What this does is define a clear cycle of coding without worrying about changes, and then merging with everyone else. When you merge, your version control system will try to do it automatically, but if there are conflicts it will compare your code with the code of other developers and allow you to make edits so that you don’t break each other’s code. That’s the idea.

The most popular version control systems these days are SVN, Git and Mercurial. We, at FaceySpacey, use Mercurial. SVN is a little older. Git and Mercurial are very comparable. They allow for what’s called “distributed version control.” I won’t go into what that means too much right now, but I will say that Git has been compared to the MacGyver of version control and Mercurial to the James Bond of version control. What that means is Git has more features (and therefore more to learn and figure out), whereas Mercurial has less features but is easier to get up and running with. The features it does have are very precise and solve what it is you will actually need most of the time really well. The reason we use Mercurial is because it integrates nicely with our bugtracker, Fogbugz. Fogbugz’s makers, Fogcreek, has a complementary product called “Kiln” which works in conjunction with Fogbugz. Basically it allows you to associate committed code to fixed bugs and completed tasks/features within Fogbugz.

So here’s how we use Mercurial.

1) Signup for Kiln here:

http://www.fogcreek.com/kiln/

They have a free startup version for 2 developers. Once you create your account, you’ll be directed to create your first repository. Create it. Some directions will be provided about how to “push” your code to this storage space on Kiln’s servers for your code.

2) Those directions will look like the following basically. At the command line navigate to your code and execute the following commands:

# cd /var/www/yoursite.com/

# hg init

# hg add

# hg commit

# hg push https://yoursite.kilnhg.com/repo/project-name/Group/repo-name

That will take the code on your server (or your local host if that’s where your’re working) and send the code to your storage space (i.e. respository) on Kiln’s servers. In essence, Kiln will keep a back up of all your code--and of course with all the “time machine” magic previously talked about. In other words, it will store snapshots of your code at all points in time--well, specifically, after all commits. A commit is made every time you type “hg commit” at the command line while within your application directory. If you type “hg commit -m ‘some notes’” you can leave some notes about the recent changes you made, and then you can easily see what code is being commited within the Kiln web interface.

The next thing to note is that in the file, /var/www/yoursite.com/.hg/hgrc, you can permanently enter your Kiln login credentials so that with every commit and push to the Kiln server you don’t have to enter the login credentials again:

[paths]

default = https://yoursite.kilnhg.com/repo/project-name/Group/repo-name

[auth]

kiln.prefix=https://yoursite.kilnhg.com/repo/project-name/Group/repo-name

kiln.username=your-kiln@email-address.com

kiln.password=yourpassword

[ui]

username= your-kiln@email-address.com

password=yourpassword

The /.hg folder fyi may be hidden, so make sure to unhide your hidden files while in your root application directory to see it.

The last thing to do is to navigate to another hidden file /var/www/yoursite.com/.hgignore and add the following lines (create this file if it does not exist already):

syntax: glob

runtime/**

assets/**

Those lines will make it so you don’t commit code that is unique to each computer that has the code on it. You may end up having an /uploads folder in your root application directory. If my app has functionality for users to do things like upload photos, i’ll make it so those large images are also not committed and pushed. Photos are big files and will make it so your commits/pushes take a long time, and won’t be needed on the computers/servers of other developers since they’ll have their own.

So that’s basically it. One of the biggest benefits of doing this is you don’t need to worry about losing all your code if your server goes down. All you’re going to have to remember really after it’s installed is to type “hg commit -m ‘some message’” after you write new code, and “hg push” to push it to the central repository. And then “hg pull” and “hg update” which you run to pull in code commits other developers pushed to the main Kiln repository. You’ll also at times have to type “hg merge” but the beauty of mercurial is that when you run any one of these commands, if there is a problem, Mercurial will let you know at the command line and suggest other commands such as the “hg merge” one that you should execute.

Let me summarize the common flow:

PUSHING YOUR NEW CODE OUT:

# hg commit

# hg push

PULLING OTHER DEVELOPERS’ CODE IN:

# hg pull

# hg merge

# hg update

That’s basically all you need to get productive quickly. When you get serious about using Mercurial, read the following longer tutorial by the Joel Spolsky, the creator of Fogbugz and Kiln (as well as Stackoverflow). He’s a prolific software developer that got his reputation from his work at Microsoft, specifically on the Excel project. Joel Spolsky’s the man. Research/google him.

http://hginit.com/