Mercurial, if you haven't played with it yet, is one of the easiest, fastest source control mechanisms to hit Windows in recent years. If you have heard of Mercurial (or Hg, as some folks will type it, the symbol on the periodic table of elements for mercury), you may think I misspoke with that "Windows" bit, since only those long-haired open source hippie Linux people use that freebie distributed version control. Not true! As a matter of fact, for your own personal projects, Hg is probably one of the easiest, fasted version control mechanisms you can use for local-only development.
Getting startedThe basic reference material you will need for Hg is available in the Mercurial wiki at http://www.selenic.com/mercurial/wiki/. Just so you don't have to read it, I'll continue below.
On your local Windows box, you will want to install TortoiseHg. If anybody has ever used the fine TortoiseSVN on Windows, you will be immediately familiar with the direct Windows Explorer integration with source control. Some of the more recent versions of TortoiseHg (0.7.6 is the latest as of this writing) include a full installation of the command-line version of Mercurial, saving Windows uses the hassle of finding and running another installer. You will eventually come up with a need for the command-line version of Hg, and you will want to become familiar with its simple commands anyway.
For Visual Studio users (Standard edition and above, sorry Express edition users. Out in the cold as usual.), you can install VisualHg to get that sweet, sweet development environment integration that the users of Visual Source Safe and TFS currently enjoy in their development experience. Once installed, you can enable the source control integration within Visual Studio by going to Tools->Options, then choosing "Source Control" in the tree view, and changing the "Current source control plug-in:" combo box.
As a side note, if you're still using VSS...please stop. SVN and Mercurial are, at the very least free, and are far less likely to corrupt your source repository. Also, if you aren't paying for each and every seat license of VSS (even if you put it on a server and share it), you're stealing from MS at the rate of about $390 a seat. Don't place your business and your code at risk by using VSS.
Beyond local development
Despite what some other ill-informed (yet admittedly old) blogs have implied, Mercurial can be hosted in IIS on Windows. Nobody's set out step-by-step instructions all in one place, but that is about to change.
For all versions of Windows
- Install Mercurial 1.2.1 on the server. The version that comes with TortoiseHg is not sufficient, it will not drive the CGI application.
- Install Python 2.5.4 on your server. Mercurial 1.2.1 components are compiled against that version of Python. Any other version of Python will cause a "Bad Magic Number" error on the server.
- Create a directory somewhere to hold the Mercurial source tree. Open a cmd window and navigate to whichever directory you want this source tree to be contained within, then type in
hg clone http://selenic.com/repo/hg(robbed from Stack Overflow). This command will create a directory named hg, then download all the code in the Mercurial source repository into the hg directory. What we're after here is is the hgwebdir.cgi file, which is...a Common Gateway Interface app. Duh. And I'll bet you thought that cgi was dead.
- Create a directory on the file system (separate from any other web app files you have on your web server) to map in as a Virtual Directory in IIS. I used C:\inetpub\hgcgi\. Make sure this directory has read access in NTFS for the service account IIS (or your IIS app pool for Vista, XP x86-64, Server 03 and Server 08) is running under.
- Copy the hgwebdir.cgi file into your virtual-directory-to-be.
- You also want to extract the contents of the Library.zip file contained in your Mercurial installation directory to your virtual-directory-to-be. If you installed TortoiseHg 0.7.6, you will find this within the TortoiseHg installation directory.
- Copy the entire "templates" directory from the Mercurial installation directory to a "templates" directory within the virtual-directory-to-be.
- Create a file named hgweb.config. This is absolutely nothing like an Asp.Net web.config. Its more like an ini file from the days of old. And you have to actually add text to it. You want something that looks like this:
MySourceCode = C:\Repositories\**
style = monoblue
The [paths] segment is in the form
= local path. You can list out repository locations manually, or you can do as above, and have it take all of the repos in a location. And yes, the ** is correct. Most of the other documentation around the web is unix-style fs specific, and suggest using the [collections] section as opposed to the [paths] section, but don't be surprised when it doesn't work on Windows. I never had any luck with using the [collections] section.
And yeah, you want to change the style. Because you can.
- Once you get your repos to show up in the Mercurial cgi script, you can go into the repo's .hg directory, find the hgrc file therein and configure it. The syntax is the same as hgweb.config, and it allows you to set settings for the repository itself. Such as the style. Because you can. Details on the config file are here.
That's everything you must do that is common to all versions of Windows.
IIS 7 (Windows Vista, Server 08)Just like everything else that is related to Vista, Microsoft changed the whole UI for the IIS Manager. This is good, because IIS Manager (just like the Component Services snap-in) in Server 2003 is a fussy, buggy, expletive-inducing wreck. IIS 7 does give you the ability to install Asp.Net "filters" (called a "Managed Handler" in IIS Parlance, called an HttpHandler in Asp.Net parlance) directly into IIS. Kinda cool really, since writing ISAPI filters requires that icky native code that seems to bamboozle so many people. Maybe someone will write a nice Managed Handler for Mercurial in the future, but for now, we have to use CGI.
- Install IIS. In Vista, its Control Panel->Programs and Features in "Classic View" or Control Panel->Programs in the new Vista view. Click on "Turn Windows features on or off." Expand "Internet Information Services", then select "Web Managment Tools" to install IIS Management Console. Select "World Wide Web Services", then expand "World Wide Web Services", then expand "Application Development Features" and make sure "CGI" is selected.
- Add your virtual directory for Mercurial. That's the one that has hgwebdir.cgi in it. Right click a web site (I just mapped it into the "Default Web Site", but any will do.), and choose "Add application" You could "Add virtual directory" and then upgrade the virtual directory to an application, but the virtual directory mapping has to be an "application." In the dialog, I set the alias to hg and the Physical path to "C:\inetpub\hgcgi". There is a nice "Test settings..." button here that will help you determine if your application directory is configured property. I never did get my authorization warning to go away, even though the CGI script would run.
- Map in the Python interpreter as a script engine. Click on your new application/virtual directory. In the center pane, double-click "Handler Mappings." Normally, if you wanted to execute Python scripts on the server, you would map the interpreter to *.py. But we're running a cgi app through the python interpreter. Click on "Add Script Map..." and put in *.cgi for the Request Path. Put
C:\Python25\python.exe -u %s %sin for Executable. Give your mapping a name. I used Python 2.5. The %s %s mess above are substitution symbols (like printf(), or string.Format()) for arguments passed to the python interpreter that tell it what script it is executing on behalf of IIS. After that, click the "Request Restrictions..." button, and choose the "Access" tab. Pick the "Execute" option, so you can "Execute" the cgi application. Click OK to save. A dialog will pop up that says "Do you want to enable this ISAPI application?", which is a bit bizarre since you are enabling a CGI application, but you should say Yes.
- Enable the script engine for your application/virtual directory. Right click your new "Python 2.5" handler mapping, and select "Edit feature permissions...", and make sure all of the checkboxes there are checked.
Windows Server 2003/XP
- Buy Server 2008. I hear that if you get it on subscription, you get free upgrades. If you can't talk your boss into paying for the next scheduled maintenance on Balmer's V12 Vantage (and if he doesn't really have one, he probably should), make sure IIS is installed on the Server. Control Panel->Add or Remove Programs, then Add/Remove Windows Components. Select Application Server, and you should be set.
- Add your virtual directory for Mercurial. That's the one that has hgwebdir.cgi in it. Right click a web site (I just mapped it into the "Default Web Site", but any will do), and choose New->Virtual Directory. In the dialog, I set the alias to hg and the Physical path to "C:\inetpub\hgcgi". By default, in Server 03, virtual directories are mapped in as "Web Applications," but if it isn't set up that way, you can right click the virtual directory, and click the "Home Directory" tab. On the bottom of that tab, in the "Application settings" section, there should be a button labeled "Add." Once you click it, the virtual directory becomes a "Web Application." Also, while you're there, make sure the "Execute permissions:" drop down says "Execute."
- Map python in as the cgi script handler. Do this by right clicking the virtual directory, then selecting the "Home Directory" tab. In the "Application settings" section, click the "Configuration" button. On the "Mappings" tab, click the "Add..." button. For "Executable", put in the following:
C:\Python25\python.exe -u "%s %s"And make sure you put the double quotes in exactly as shown. This is because IIS Manager is and won't take it without them. In "Extension", put ".cgi". Clear the checkbox that says "Verify that file exists", set the checkbox that says "Script engine."
- Enable Python as Web Service Extension (Server 03/XP x64). In IIS Manager, right-click the Web Service Extension to "Add a new Web service extension...". You can name the extension anything you want, I chose "Python 2.5". Click the "Add..." button. In "Path to file", put C:\Python25\python.exe -u "%s %s". It must exactly match the ".cgi" mapping on your virtual directory, or it won't work. Check "Set extension status to Allowed".
Point your browser to http://server/HgVDir/hgwebdir.cgi/ and enjoy. You should now be able to use Mercurial against that virtual directory. To secure your source control repository, you should set up SSL on your server, and mark your hg virtual directory to require SSL. Then set the virtual directory to use Basic security, as this is what the hg client tools support. Basic-over-SSL is pretty secure, since the SSL encrypted connection is established well before the Basic security credential exchange takes place.
To create new repos on the server, you'll want to clone them to the server from your workstation machine. The easiest way to do this is to hg serve from your workstation, then log onto the server and pull your new repo into the right place on the server from your workstation. After that, go into .hg in your server-side repo and configure your hgrc file. Once that is complete, you can synchronize your server repo with your workstation repo any time you wish.
And just in case you're wondering, the -u switch on the python interpreter places the interpreter in "unbuffered" mode, so results are sent to IIS immediately with no delay. Supposedly, for CGI, it improves performance.
Give hg a shot. Its effective and I've had quite a bit of success with it. Maybe you'll like it, too.