Copyright (C) 2011 Sven Erik Knop / Perforce Software

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

1.  Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.

2.  Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in the
    documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL PERFORCE
SOFTWARE, INC. BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
DAMAGE.


Mercurial - Perforce converter
==============================

This is a quick overview of how you can enhance the latest 
Mercurial installation to convert Hg repositories to Perforce.
You need:

1. The standard Mercurial code (I used Hg 1.7.3). You can use the full
installation I provided here, or load the code from the Mercurial website.

2. Two modified files from my installation:

hgext/convert/p4.py			# added P4_sink class
hgext/convert/convcmd.py	# simply declares P4 a valid sink

Place these two files into the standard Mercurial code and re-build.

3. P4Python 2010.1 or later. 
Download this from the Perforce ftp server or website. 
You will also need the P4 API libraries for your platform in order
to build the P4Python extension. Please follow the release notes 
provided on how to build and install P4Python.

P4Python is a thin wrapper around the P4 API that allows Python users
to access the Perforce commands and a simple and concise interface. This
beats the alternative to wrap the P4 command line command (and is faster 
to boot).

4. Convert is a standard extension for Mercurial I have extended 
for export to Perforce. You enable this extension by putting the 
following lines into your .hgrc file:

[extensions]
convert =

5. Create an authormap in the directory you run the converter in. 
This file is a text file that maps the Mercurial user information 
to the Perforce information. In my tests, this file contains one line:

Sven Erik Knop <sknop@perforce.com>=sknop

You can use 'hg log' to find all committed changes in your Mercurial 
repository. Filter these for "user:" and extract the second part to
the user. The output then needs to be sorted for unique entries.
You need to be prepared map several entries to one Perforce user,
since the user entry in hg is self-declared and not enforced anywhere.

6. Create a workspace for import. Place the workspace root outside your hg repository. 
Make sure to enable the option 'allwrite' to avoid error messages.

7. Start the import. Here is the command I used

/path/to/hg convert -A authormap -v --config convert.p4.client=hg-import-main \
--config convert.p4.port=1666 --config convert.p4.user=sknop --dest-type p4 .

Note the '.' at the end which is the location of the hg repository. Make sure to use the 'hg' 
executable (in fact a Python script) from your build (see step 2) to ensure you pick up the correct convert libraries.

The export will create a file called revmapfile which maps Mercurial rev hashes to Perforce changes. 
This can be used to create incremental imports.
You need to delete this file if you want to re-run the import again from scratch. 

Good luck.