So I decided to convert my Mercurial repository to Git using the hg-git Mercurial plugin and ran into a lot of issues along the way. Here is a guide to successfully getting the hg-git plugin to work on a Windows machine:

1. Install TortoiseHg if you haven’t already

If you’re developing on Windows and using Hg, you probably already have TortoiseHg installed. If not, go ahead and download and install TortoiseHg. Make a note of where you install TortoiseHg, since you need to make some modifications in this directory.

2. Install the prerequisites for the hg-git plugin

We’re going to use the hg-git Mercurial plugin to allow us to pull from and push to any Git repository. This has a dependence on Mercurial (which is handled by installing TortoiseHg in the previous step) and dulwich which is a library that provides an interface to git repos using pure Python code.

However since you most probably don’t have Python installed on your Windows machine, follow these steps to “install” the dulwich library for use by the hg-git plugin:

1. Download the latest source code for dulwich (version 0.4.0 or above) and unzip it to a temporary directory
2. IMPORTANT: Read the note at the bottom of the post for troubleshooting. You might need to make a change to a file in the dulwich folder in order for it to work on Windows.
3. Under the newly unzipped folder, you should see a directory called “dulwich” which contains all the Python code (you should see a bunch of files with the .py extension)
4. In the installation directory for your TortoiseHg installation, you should see a zip file called library.zip. Copy the dulwich folder into this zip file in the root of the zip file.

3. Download the source code for the hg-git Mercurial plugin

Clone the repository at http://bitbucket.org/durin42/hg-git/ to a location on your hard drive, say C:\hg\hg-git

4. Setup .hgrc to use the hg-git plugin

Navigate to the hg repository on your hard drive that you want to convert to Git. Under the .hg directory, edit the hgrc file to contain the following three lines:

[extensions]
hgext.bookmarks =
hggit = C:\hg\hg-git\hggit

You need to point hggit in your hgrc file to point to the subdirectory called “hggit” located in the cloned repository (see step 3 above). This folder usually only contains Python code files (with a .py extension)

5. Pull and push from a Git repository

That’s it! Provided your current working directory is inside the hg repository that you set up, you should be able to pull from and push to any Git repository.

Troubleshooting

1. If you’re getting a error about a function called build_tree in index.py, you need to add the line  to the very top of the build_tree(path) method as follows. Once you’ve added this line, you can add the dulwich folder to zip file as in step 2:

def build_tree(path)
    path = path.replace ("\\", "/")

2. If you’re getting an error like “abort: The system cannot find the file specified”, then dulwich cannot find ssh in your PATH. You need to make sure to install Cygwin’s OpenSSH and that you can run “ssh” from the command line.

3. If you get “Permission denied (publickey)”, it just means that the public key required to access and push to the server cannot be found. To get around this we’re going to run the following commands:

ssh-agent
ssh-add <full path to your key file>

Controller code

The code is pretty simple, except that I am specifying the page to show to be equal to params[:user_page] and params[:administrator_page] respectively. Since we are allowing the ability to page over two models, we need two separate parameters to determine which page of users or administrators to show.

@users = User.paginate(:page => params[:user_page], :per_page => 10)
@administrators = Administrator.paginate(:page => params[:administrator_page], :per_page => 10)

View code

In the view all we need to do is make sure to set the param_value to the correct value to indicate to the plugin that we want to use a different parameter name for the page. The default is simply called ‘page’, but we need to make sure to use ‘user_page’ and ‘administrator_page’ instead for the two different models.

<%= will_paginate @users, :param_name => 'user_page' %>
<%= will_paginate @administrators, :param_name => 'administrator_page' %>

That’s it, you should now be able to page through your users and administrators on the same page.

I’m a big fan of Behavior Driven Development and all the code you see below was driven by a customer’s acceptance test for a vital business feature. In order to keep this simple, I’m just going to describe how I used RSpec to drive the file upload code, but feel free to read the RSpec book to get more information on BDD with Ruby on Rails.

Designing the Document class

Since all our business rules and logic belongs to our domain model, the Document class has to be smart. It should know how to store uploaded files on the server, how to handle file name clashes etc. The controller should be able to simply call a method on this class to store an uploaded file correctly. This is the RSpec example for the save_upload method in the Document class:

it "should be able to save an upload with an unique name generated by using a timestamp" do
  # As of Rails 2.3.2, the framework passes an UploadedStringIO to the controller when uploading files
  # I'm creating a mock that I can pass to my save_upload method on my Document class.
  # The save_upload only requires that the passed in object respond to original_filename and read.
  uploaded_file = mock(ActionController::UploadedStringIO).as_null_object
  uploaded_file.stub!(:original_filename).and_return('test.doc')
  uploaded_file.stub!(:read).and_return("Some content")

  document = Document.new

  document.save_upload(uploaded_file)
  document.original_filename.should == "test.doc"
  # To prevent file name clashes, the saved file's new name is prepended with a timestamp
  document.new_filename.should =~ /\d{2}\d{2}\d{4}\d{2}\d{2}\d{2}-test.doc/
  # Finally, does the file exist on the file system and if so are the contents of this file correct?
  File.exist?("#{Rails.root}/public/system/documents/#{document.new_filename}").should == true
  File.open("#{Rails.root}/public/system/documents/#{document.new_filename}", "r") { |f| f.read.should == uploaded_file.read }
end

Implementing the Document class’s save_upload method

Once we’ve got the RSpec example, writing the actual code to make the example pass is pretty simple.

def save_upload(upload)
  self.original_filename = sanitize_file_name(upload.original_filename)
  self.new_filename = unique_filename
  # Write the file
  File.open(absolute_path, "wb") { |f| f.write(upload.read) }
end

private
  def absolute_path
    File.join(Rails.root, 'public/system/documents', self.new_filename)
  end

  def sanitize_file_name(filename)
    # Internet explorer returns the complete path to the file, instead of just the file name that was uploaded.
    # File.basename gives us just the filename and fixes the above issue with Internet Explorer.
    # Replace everything other than alphanumeric characters, periods or underscores with underscores to ensure
    # there are no illegal characters
    File.basename(filename).gsub(/[^\w\.\_]/, '_')
  end

  def unique_filename
    # Prepend a timestamp to the original filename to create a unique filename
    Time.now.strftime("%m%d%Y%H%M%S").to_s + "-#{self.original_filename}"
  end

Designing the controller code

Now that we’ve got all the business logic required for saving an uploaded file in the Document class, the actual code for the controller method is pretty simple. All we need to do is check that the document’s save_upload method is called with the correct parameter.

it "should save the uploaded document" do
  document = mock(Document).as_null_object

  Document.should_receive(:new).and_return(document)
  uploaded_file = mock(ActionController::UploadedStringIO).as_null_object
  params = { "id" => "1", "document" => uploaded_file }
  document.should_receive(:save_upload).with(uploaded_file)
  post :save_file, params
end

Implementing the controller code

Getting this RSpec example to pass is pretty simple. The controller code simply creates a new Document object and then calls the save_upload method with the correct form parameter.

  def save_file
    if params[:document] != nil
      document = Document.new
      document.save_upload(params[:document])
    end
  end

Phusion Passenger fills up most of the configuration in nginx.conf for you with a nice set of defaults. You just have to do a little more work if you want to modify the nginx configuration file to enable SSL on your site.

The first thing to do is purchase a SSL certificate and install it on your server. If you don’t know how, here’s a great post on installing SSL on Ubuntu with nginx. Once you’ve installed the certificate, you should be good to go.

Let’s say that you’ve got a domain name called mydomain.com and the root for your Ruby on Rails application is located at /home/mydomain/current/public on your server. The following shows a sample of the configuration required to get SSL enabled for your application:

server  {
    	       listen 80;
               server_name mydomain.com;
               root /home/mydomain/current/public;
               passenger_enabled on;
               rails_env production;
        }

# HTTPS server
server  {
               listen 443;
               server_name mydomain.com;
               root /home/mydomain/current/public;
               passenger_enabled on;
               rails_env production;

               ssl on;
               ssl_certificate /etc/ssl/certs/mydomain.com.crt;
               ssl_certificate_key /etc/ssl/private/mydomain.com.key;

               ssl_session_timeout  5m;
        }

Step 1: Download and unzip the source code for OpenSSL

Make sure to visit OpenSSL to determine the name of the latest source code tarball to download. In my case it was openssl-1.0.0-beta3.tar.gz

cd /tmp
wget http://www.openssl.org/source/openssl-1.0.0-beta3.tar.gz
tar -xvzf openssl-1.0.0-beta3.tar.gz

Step 2: Download and unzip the source code for nginx

Make sure to visit nginx to determine the name of the latest source code tarball to download. In my case it was nginx-0.8.14.tar.gz

wget http://sysoev.ru/nginx/nginx-0.8.14.tar.gz
tar zxf nginx-0.8.14.tar.gz

Step 3:Install and run Phusion Passenger

gem install passenger
passenger-install-nginx-module

• Watch Phusion Passenger do its thing and when it asks you “Automatically download and install Nginx?”, answer 2
• Specify the directory where you unzipped the nginx source code (/tmp/nginx-0.8.14 in my case)
• Specify the directory where you want to install nginx to (/opt/nginx in my case)
• When asked “Extra arguments to pass to configure script:”, reply with:

--with-http_ssl_module --with-openssl=/tmp/openssl-1.0.0-beta3

Keep in mind that if you downloaded the latest version of the source code, your values might be slightly different from mine.

That’s it! I’ve also posted a sample configuration file for nginx to enable SSL.