<?xml version="1.0" encoding="UTF-8"?><!-- vim: set ts=2 sw=2 tw=80 ai si: --><?xml-model href="http://www.oasis-open.org/docbook/xml/5.0/rng/docbookxi.rng" schematypens="http://relaxng.org/ns/structure/1.0"?><?xml-model href="http://www.oasis-open.org/docbook/xml/5.0/rng/docbook.rng" type="application/xml" schematypens="http://purl.oclc.org/dsdl/schematron"?><book xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"><?dbhtml filename="copyright.html"?>
  <title>P4Convert: User Guide</title>
  <subtitle>April 2015</subtitle>

  <info>
    <publishername>Perforce</publishername>

    <copyright>
      <year>2007-2015</year>
      <holder>Perforce Software.</holder>
    </copyright>

    <legalnotice>
      <para>
        All rights reserved.
      </para>

      <para>
        P4Convert is supplied by Perforce Software in the hope that it will
        be useful. It is a support utility, not a Perforce product. All use of
        this software is at the user's own risk and subject to the following
        terms and conditions.
      </para>

      <para>
        THIS SOFTWARE IS PROVIDED BY PERFORCE SOFTWARE, INC. '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.
      </para>
    </legalnotice>
  </info>

  <!-- vim: set ts=2 sw=2 tw=80 ai si: --><?xml-model href="http://www.oasis-open.org/docbook/xml/5.0/rng/docbookxi.rng" schematypens="http://relaxng.org/ns/structure/1.0"?><?xml-model href="http://www.oasis-open.org/docbook/xml/5.0/rng/docbook.rng" type="application/xml" schematypens="http://purl.oclc.org/dsdl/schematron"?><preface xml:id="about" version="5.0" xml:base="00_preface.xml"><?dbhtml filename="index.html"?>
  <title>What is p4convert for?</title>

  <para>
    The p4convert conversion tool imports data from Subversion or CVS and
    reconstructs the file revision history in Perforce. For CVS the data is
    read from the CVSROOT and for Subversion data is read from a dump file.
    Data is added to Perforce in one of two ways:
  </para>

  <section xml:id="about.import_mode">
    <title>Import Mode (front door)</title>

    <para>
      Revisions are imported into a running Perforce Server. The Perforce 
      Server could be new or contain existing data, but it must be running.
      Subversion revisions are added sequentially; file content is 'imported'
      and metadata such as file attributes, descriptions, dates and usernames
      are added to the Perforce changelist.  CVS data is sorted into 
      changeslists, based on available metadata such as date/time, author, 
      change descriptions and file actions.
    </para>

    <para>
      The recommended use of Import Mode is to start a new Perforce server to
      import each set of changes into a Perforce changelist. Using this
      method will produce a one-to-one mapping of Subversion revision numbers
      to Perforce changelists and a reproducible set of CVS changes. The new 
      Perforce server can be used in isolation to confirm the success of the
      migration and then merged with an existing Perforce Server using the
      <application>PerfMerge++</application> tool.
    </para>
  </section>

  <section xml:id="about.convert_mode">
    <title>Convert Mode (back door)</title>

    <para>
      Revisions are converted in full, creating a Perforce journal and set
      of archive files. Once replayed, the resulting conversion is just as if
      the changes had always been in Perforce. The results can be merged into
      an existing Perforce Server using the
      <application>PerfMerge++</application> tool. The Import Mode is
      considered to be the safest method as all files are imported through a
      Perforce Client. Convert Mode is significantly faster, but requires an
      understanding of Perforce database administration.
    </para>

    <para>
      Convert Mode is an advanced feature and should only be attempted by a
      Perforce expert familiar with replaying and upgrading databases.
      Incremental conversions are not supported using Convert Mode; however
      Import Mode can be used after a Convert Mode conversion to update the
      migration.
    </para>
  </section>

  <section xml:id="about.incremental_updates">
    <title>Incremental Updates (front door)</title>

    <para>
      Incremental Subversion updates are possible only using the Import Mode
      where new revisions from Subversion are imported into Perforce. However,
      no changes should be made to the import area of the Perforce Server or
      conflicts may occur.
    </para>
    
    <para>
      Incremental CVS imports are not currently supported in either Import or
      Convert Mode.
    </para>
  </section>
</preface>
  <!-- vim: set ts=2 sw=2 tw=80 ai si: --><?xml-model href="http://www.oasis-open.org/docbook/xml/5.0/rng/docbookxi.rng" schematypens="http://relaxng.org/ns/structure/1.0"?><?xml-model href="http://www.oasis-open.org/docbook/xml/5.0/rng/docbook.rng" type="application/xml" schematypens="http://purl.oclc.org/dsdl/schematron"?><chapter xml:id="chapter.setup" version="5.0" xml:base="01_setup.xml">
  <title>Setup</title>

  <section xml:id="setup.requirements">
    <title>System Requirements</title>

    <orderedlist>
      <listitem>
        <para>
          [SVN] an unzipped Subversion dump file of the repository to be converted
          (generated without the <parameter>--delta</parameter> flag).
        </para>
      </listitem>

      <listitem>
        <para>
          [CVS] an unzipped CVSROOT directory containing the RCS files of the 
          repository to be converted.
        </para>
      </listitem>

      <listitem>
        <para>
          System must have <emphasis role="bold">Java SE Runtime 1.7</emphasis>.
        </para>
      </listitem>

      <listitem>
        <para>
          System must have the Perforce Server binaries 2010.2 or greater.
        </para>
      </listitem>

      <listitem>
        <para>
          [Import Mode] A running Perforce Server (typically empty) with no
          pending changes in the conversion area.
        </para>
      </listitem>

      <listitem>
        <para>
          [Convert Mode] An empty Perforce Root directory for the generated
          archive and journal files.
        </para>
      </listitem>
    </orderedlist>

    <section xml:id="setup.requirements.resource_tips">
      <title>Resource Tips:</title>

      <para>
        Running some conversions, particularly in Conversion Mode can
        be very memory intensive, as a mapping of revisions and integrations
        is kept in memory. For large conversions, or conversions with
        excessive branching, more memory will needed by the JVM.
      </para>

      <para>
        The <parameter>--info</parameter> option will scan the Subversion dump
        file and report usage data to help estimate the required memory for
        Convert Mode. For example:
      </para>

<programlisting language="bash">
java -jar p4convert.jar --type=SVN --repo=&lt;path_to_svn_dumpfile&gt; --info 
</programlisting>

      <para>
        Use the <parameter>-Xmx</parameter> flags to increase the memory
        allocated to the JVM. For example, to allocate 64GB (65536MB) use:
      </para>

<programlisting language="bash">
java -Xmx65536M -jar p4convert.jar --config=myConfig.cfg
</programlisting>
    </section>
  </section>

  <section xml:id="setup.caveats">
    <title>Caveats</title>

    <orderedlist>
      <listitem>
        <para>
          The following table lists the combinations of tested operating systems
          and Perforce Server versions.
        </para>

        <informaltable>
          <tgroup cols="3">
            <colspec colname="os" colwidth="2*"/>
            <colspec colname="10.2" colwidth="*"/>
            <colspec colname="14.1" colwidth="*"/>
            <thead>
              <row>
                <entry><para>Operating System</para></entry>
                <entry><para>10.2</para></entry>
                <entry><para>14.1</para></entry>
              </row>
            </thead>

            <tbody>
              <row>
                <entry><para>Ubuntu 10.04</para></entry>
                <entry><para>supported</para></entry>
                <entry><para>supported</para></entry>
              </row>

              <row>
                <entry><para>Darwin 11.4.0</para></entry>
                <entry><para>supported</para></entry>
                <entry><para>supported</para></entry>
              </row>

              <row>
                <entry><para>Windows 7x64</para></entry>
                <entry><para>supported</para></entry>
                <entry><para>supported</para></entry>
              </row>

              <row>
                <entry><para>SunOS 5.10</para></entry>
                <entry><para>supported</para></entry>
                <entry><para>supported</para></entry>
              </row>
            </tbody>
          </tgroup>
        </informaltable>

        <para>
          It is likely that other combinations will work, however it is not
          possible to test all combinations.
        </para>

        <para>
          Please contact Perforce if you have any OS or version queries.
        </para>
      </listitem>
    
      <listitem>
        <para>
          [Import Mode] Symbolic links are not supported in Import Mode on
          Windows.
        </para>
      </listitem>

      <listitem>
        <para>
          Perforce keyword expansions are different from the Subversion 
          standard and may yield different results when synced.  CVS keyword
          detection is not yet supported.
        </para>
      </listitem>
    </orderedlist>
  </section>

  <section xml:id="setup.usage">
    <title>Setup and Usage</title>

    <para>
      Download the self-contained JAR from Perforce and check that Java SE
      runtime is installed with version 1.7 or greater.
    </para>

    <para>
      For usage details, execute the jar with no options:
    </para>

<programlisting language="bash">
usage: java -jar p4convert.jar
 -c,--config &lt;arg&gt;    Use configuration file
 -d,--default         Generate a configuration file
 -E,--end &lt;arg&gt;       End revision, for incremental (SVN)
 -e,--extract &lt;arg&gt;   Extract a revision
 -i,--info            Report on repository usage
 -r,--repo &lt;arg&gt;      Repository file/path
 -S,--start &lt;arg&gt;     Start revision, for incremental (SVN)
 -t,--type &lt;arg&gt;      SCM type (CVS | SVN)
    --tags &lt;arg&gt;      find tags to specified depth
    --tree &lt;arg&gt;      (with --info), display tree to specified depth
 -u,--users           List repository users
 -v,--version         Version string

Example: standard usage.
   java -jar p4convert.jar --config=myFile.cfg

Example: generate a CVS configuration file.
   java -jar p4convert.jar --type=CVS --default

Example: report Subversion repository usage.
   java -jar p4convert.jar --type=SVN --repo=/path/to/repo.dump --info
</programlisting>

    <para>
      To create a default configuration file using the <parameter>--default</parameter>
      option. You will need to specify the SCM type using <parameter>--type</parameter> 
      (with a value of SVN or CVS). The generated file (default.cfg) will 
      contain a set of default configuration options based on your platform.
      Rename the <parameter>default.cfg</parameter> to your own configuration.
      To run a conversion using your configuration file, execute the jar with 
      the <parameter>--config</parameter> flag specifying you config file.
      For example:
    </para>

<programlisting>
java -jar p4convert.jar --config=myFile.cfg
</programlisting>

  </section>

  <section xml:id="setup.generate_dump_file">
    <title>Generating a Subversion Dump file</title>

    <para>
      For Subversion conversions, both Import and Convert modes require a 
      Subversion dumpfile as the historic data source. A dumpfile can be 
      generated in several different ways, two of which are detailed below:
    </para>

    <itemizedlist>
      <listitem>
        <para>
          Using the svnadmin command:
        </para>

<programlisting language="bash">
svnadmin dump <replaceable>local_repo_path</replaceable> &gt; dumpfile.dmp
</programlisting>

        <para>
          Replace <replaceable>local_repo_path</replaceable> with the path to
          the Subversion repo. Do not use the <parameter>--delta</parameter>
          flag option as the results cannot be parsed by the conversion tool.
        </para>
      </listitem>

      <listitem>
        <para>
          Using the remote dump command:
        </para>

<programlisting language="bash">
rsvndump <replaceable>url</replaceable> &gt; dumpfile.dmp
</programlisting>

        <para>
          Replacing <replaceable>url</replaceable> with the remote Subversion
          server. For example: <literal>http://</literal> or
          <literal>file://</literal> or <literal>svn://</literal>.  Note that
          for large servers generating the dump file locally is significantly
          faster, so you might also consider creating a local copy of the
          subversion depot using
          <link xlink:href="http://svn.apache.org/repos/asf/subversion/trunk/notes/svnsync.txt">svnsync</link>,
          before generating the dump file.
        </para>
      </listitem>
    </itemizedlist>
  </section>
  
  <section xml:id="setup.cvs_root">
    <title>Selecting a CVS root</title>

    <para>
      For CVS conversions, both Import and Convert modes require a path
      containining RCS files as the historic data source. CVSROOT can be filtered
      or imported on a per module basis.  The converter will only import file
      revisions under the specified CVSROOT path.
    </para>
  </section>
</chapter>
  <!-- vim: set ts=2 sw=2 tw=80 ai si: --><?xml-model href="http://www.oasis-open.org/docbook/xml/5.0/rng/docbookxi.rng" schematypens="http://relaxng.org/ns/structure/1.0"?><?xml-model href="http://www.oasis-open.org/docbook/xml/5.0/rng/docbook.rng" type="application/xml" schematypens="http://purl.oclc.org/dsdl/schematron"?><chapter xml:id="chapter.config" version="5.0" xml:base="02_config.xml">
  <title>Configuration</title>

    <para>
      The java conversion requires a configuration file to setup the necessary
      options. A default configuration file <filename>default.cfg</filename> can
      be generated by running the converter with the <parameter>--default</parameter>
      parameter and specifying <parameter>CVS</parameter> or <parameter>SVN</parameter>.
    </para>
    
    <para>
      For example: to generate a default configuration file for CVS, run...
    </para>

<programlisting language="bash">
java -jar p4convert.jar --type=CVS --default
</programlisting>

  <para>
    Once you have <filename>default.cfg</filename>, copy it to
    <filename>yourconfig.cfg</filename> and then customize it as needed for
    the conversion.
  </para>

  <section xml:id="config.general.core">
    <title>
      Core converter settings.
    </title>
      
    <para>
      The following settings appear at the top of the configuration file 
      and are automatically defined at the time of generation.  The
      Core converter settings should not be modified.
    </para>

    <orderedlist>
      
      <listitem>
        <para>
          Configuration file schema version. Used to identify older configuration
          formats.
        </para>
<programlisting language="ini">
com.p4convert.core.schema=<replaceable>5.50</replaceable>
</programlisting>
        </listitem>
        
      <listitem>
        <para>
          SCM conversion type.  Either set SVN or CVS configuration options.
        </para>
<programlisting language="ini">
com.p4convert.core.scmType=<replaceable>SVN</replaceable>
</programlisting>
      </listitem>    
        
      <listitem>
        <para>
          Reserved for testing framework.  Must be set to <literal>false</literal>
          for normal operation.
        </para>
<programlisting language="ini">
com.p4convert.core.test=<replaceable>false</replaceable>
</programlisting>
      </listitem>  
        
      <listitem>
        <para>
          Conversion tool's release version.
        </para>
<programlisting language="ini">
com.p4convert.core.version=<replaceable>PUBLIC.10690</replaceable>
</programlisting>
      </listitem>  
        
    </orderedlist>
  </section>
    
  <section xml:id="config.general.p4">
    
    <title>
      General Perforce converter settings.
    </title>
      
    <orderedlist>

      <listitem>
        <para>
          Set the conversion mode to <literal>IMPORT</literal> for Import Mode
          and to <literal>CONVERT</literal> for Conversion Mode.
        </para>
<programlisting language="ini">
com.p4convert.p4.mode=<replaceable>IMPORT</replaceable>
</programlisting>
      </listitem>

      <listitem>
        <para>
          Import depot path and depot to be created, e.g.
          <literal>//<replaceable>import</replaceable>/...</literal>
        </para>
<programlisting language="bash">
com.p4convert.core.depotPath=<replaceable>import</replaceable>
</programlisting>
      </listitem>

      <listitem>
        <para>
          An optional sub path can be specified below the depot, e.g.
          <literal>//import/<replaceable>sub</replaceable>/...</literal> (Note
          that the path must end with a slash (<literal>/</literal>) even if
          no path is used). The default value is <literal>/</literal>.
        </para>
<programlisting language="bash">
com.p4convert.core.subPath=<replaceable>sub</replaceable>/
</programlisting>
      </listitem>
    </orderedlist>
  </section>
    
  <section xml:id="config.general.svn">
    <title>
      General Subversion converter settings.
    </title>  

    <para>
      If the configuration file has been correctly generated using the 
      <parameter>--type=SVN --default</parameter> the Subversion configuration
      options will appear as a block using the <parameter>com.p4convert.svn
      </parameter> name space.  These settings will only apply if the SCM
      mode is set to <parameter>SVN</parameter>:
<programlisting language="ini">
com.p4convert.core.scmType=<replaceable>SVN</replaceable>
</programlisting>      
    </para>
      
    <orderedlist>
    
      <listitem>
        <para>
          Local path to Subversion dump file.
        </para>

<programlisting language="ini">
com.p4convert.svn.dumpFile=<replaceable>/Users/bruno/MyDumpFile.dmp</replaceable>
</programlisting>
      </listitem>
      
    </orderedlist>
  </section>
    
  <section xml:id="config.general.cvs">
    <title>
      General CVS converter settings.
    </title>  
 
     <para>
      If the configuration file has been correctly generated using the 
      <parameter>--type=CVS --default</parameter> the CVS configuration
      options will appear as a block using the <parameter>com.p4convert.cvs
      </parameter> name space.  These settings will only apply if the SCM
      mode is set to <parameter>CVS</parameter>:
<programlisting language="ini">
com.p4convert.core.scmType=<replaceable>CVS</replaceable>
</programlisting>      
    </para>

    <orderedlist>
    
      <listitem>
        <para>
          Local path to CVSROOT files. (A deeper path is permitted to limit 
          the scope of the import).
        </para>
<programlisting language="ini">
com.p4convert.cvs.cvsroot=<replaceable>/Users/bruno/CVSROOT/</replaceable>
</programlisting>
      </listitem>
      
      <listitem>
        <para>
          (Optionally) specify a CVS module to import from within the CVSROOT. 
        </para>
<programlisting language="ini">
com.p4convert.cvs.cvsmodule=<replaceable>projX</replaceable>
</programlisting>
      </listitem>

      <listitem>
        <para>
          CVS time window.  When no <parameter>commitid</parameter> is 
          defined in the RCS file, the converter will calculate which
          revisions should be grouped into a changelist.  The time window
          specifies the maximum range the converter should look ahead for
          matching revisions. (milliseconds)
        </para>
<programlisting language="ini">
com.p4convert.cvs.timeWindow=<replaceable>20000</replaceable>
</programlisting>
      </listitem>
      
      <listitem>
        <para>
          CVS temporary directory.  All the CVS assets are reformatted into
          full text files. The specified temporary directory is used to store
          the content during conversion. 
        </para>
<programlisting language="ini">
com.p4convert.cvs.tmpDir=<replaceable>tmp</replaceable>
</programlisting>
      </listitem>
            
    </orderedlist>     
  </section>
  
  <section xml:id="config.mapping_CVS_paths">
    <title>Mapping CVS Paths</title>
    
    <para>
      CVS paths are mapped into Perforce using the original RCS file structure, but
      prefixed with the branch name. The converter uses a branch name 'main' for the
      initial 1.1 branch and the symbol names for subsequent branches.
    </para>
    
    <para>  
      If requires an optional path map can be provided to remap the CVS path to a new
      structure within Perforce.  When designing a path map, care must be taken to 
      insure that all CVS paths have a destination mapping.
    </para>
    
    <orderedlist>
      <listitem>
        <para>   
          To enable CVS path mapping create a file called <parameter>path.map</parameter>
          with regex and group match.
        </para>
      </listitem>
    
      <listitem>
        <para>
          Only the first matching entry is used.  
        </para>
      </listitem>
    
      <listitem>
        <para>  
          The regex and group match are seperated by ', ' (or in regex terms ',\s+').
        </para>
      </listitem>
    
      <listitem>
        <para>  
          Lines starting with '#' are ignored.
        </para>
      </listitem>
    </orderedlist>
    
    <para> 
      For example, 'trunk' is renamed to 'main', but other entries are left as-is.
      
<programlisting language="perl">
# path.map
trunk/(.*), //import/main/{1}
(.*), //import/{1}
</programlisting>

      Note: if no file is found the default 'depot' and 'subPath' options are used to
      generate the map, preserving the original behaviour.

      CVS paths will always stat with the 'branch' name.  'main' for 1.1 and the symbol
      for other branches.

<programlisting language="perl">
# path.map
main/projA/(.*), //import/projA/MAIN/{1}
release_(.*)/projA/(.*), //import/projA/REL{1}/{2}
(.*)/projA/(.*), //import/projA/TAG-{1}/{2}
(.*), //import/unexpected/{1}
</programlisting>

      <note>
        Adding a catch all is a good idea (as shown in the last line with the
        'unexpected' directory).
      </note>
    </para>      
  </section>
    
  <section xml:id="config.labeling_CVS_paths">
    <title>Labeling CVS Paths</title>
    
    <para>
      CVS will tag revisions with symbols, some of these symbols may refer to 
      labels, whilst others are branch names.  If labeling is disabled (default),
      then only symbols with history are converted to Perforce branches, the
      remaining symbols are ignored.  However, if labels are enabled then the 
      remaining symbols from the branch detection are converted to Perforce Labels.
    </para>

    <orderedlist>
    
      <listitem>
        <para>
          To enable labeling of CVS symbols tags, set the 
          <parameter>com.p4convert.cvs.labels</parameter> to 
          <parameter>true</parameter>.
        </para>
      </listitem>
      
      <listitem>
        <para>
          In multiple CVS conversions there is the potential for namespace clashing 
          if the label has been previously used. By default, the converter will use 
          the CVS symbol as the name for the Perforce label.  However, this can be 
          formatted by setting the following option:
          <parameter>com.p4convert.cvs.labelFormat</parameter>. The parameter         
          <parameter>{symbol}</parameter> will be substituted by the CVS symbol name.
        </para>
        
        <para>
          For example:
<programlisting language="ini">
com.p4convert.cvs.labels=true
com.p4convert.cvs.labelFormat=import_{symbol}_label
</programlisting>
          Will import a CVS symbol called <parameter>REL1.0</parameter> as a Perforce
          label <parameter>import_REL1.0_label</parameter>.
        </para>
      </listitem>
      
    </orderedlist>
  </section>

  <section xml:id="config.general.selective_and_incremental_conversions">
    <title>Subversion: Selective and Incremental Conversions</title>

    <orderedlist>
      <listitem>
        <para>
          The Subversion revision ranges can be limited using the configuration
          options <parameter>startRevision</parameter> and
          <parameter>endRevision</parameter>. The default is to start at
          revision 1 and import all revisions, defined by setting
          <parameter>endRevision</parameter> to 0.
        </para>

<programlisting language="ini">
com.p4convert.svn.start=1
com.p4convert.svn.end=0
</programlisting>
      </listitem>

      <listitem>
        <para>
          Incremental conversions are possible using the Import Mode. It is
          important to take note of the last imported Subversion revision and
          start from the next revision for the subsequent import. For example:
          to import the first 100 subversion revisions, set the config options
          to:
        </para>

<programlisting language="ini">
com.p4convert.svn.start=1
com.p4convert.svn.end=100
</programlisting>
      </listitem>

      <listitem>
        <para>
          At the start of the import the following summary is displayed: (In
          this example only the first 100 revisions are imported out of 23000.)
        </para>

<screen>
Importing Subversion ranges:
  start: 1
  end:   100
  last:  23000
</screen>
      </listitem>

      <listitem>
        <para>
          For the next incremental import (say another 100 revisions) set the
          revision ranges to...
        </para>

<programlisting language="ini">
com.p4convert.svn.start=101
com.p4convert.svn.end=200
</programlisting>
      </listitem>
      
      <listitem>
        <para>
          The start and end revisions can be override on the command line
          using the <parameter>--start</parameter> and 
          <parameter>--end</parameter> flags.  For example, importing just
          Subversion revision 201.
        </para>

<programlisting language="ini">
java -jar convert.jar --config=default.cfg --start=201 --end=201
</programlisting>
      </listitem>
      
      <listitem>
        <para>
          In adition to overriding the start and end revisions you can 
          override Subversion dump file location using the 
          <parameter>--repo</parameter> flags.  For example, a range of
          revisions from an incremental dump.
        </para>

<programlisting language="ini">
svnadmin dump /path/to/repo/ -r 202:300 --incremental &gt; 202-300.dump

java -jar convert.jar --config=default.cfg --repo=202-300.dump --start=202 --end=300
</programlisting>
      </listitem>
      
    </orderedlist>
  </section>

  <section xml:id="config.filtering_subversion_paths">
    <title>Filtering Subversion paths</title>

    <para>
      The default behavior is not to exclude any path in Subversion; however for
      large repositories with many <filename>tags/</filename> folders or
      situations where only part of a Subversion repository is to be converted
      you may wish to exclude certain Subversion paths. Subversion path
      exclusion is possible using two map files <filename>exclude.map</filename>
      and <filename>include.map</filename>.
    </para>

    <para>
      The filtering is based on matching the Subversion path to a regular
      expression in the map files. The <filename>exclude.map</filename> file is
      processed first and if the pattern matches part of the path then that path
      is skipped. The <filename>include.map</filename> file can be used to
      overlay the <filename>exclude.map</filename> file re-adding paths that
      were skipped. Before a conversion can start the filters must be verified
      against the Dump file (typically this is fairly quick and a displays a
      progress indicator).
    </para>

    <para>
      The verification step is to prevent the situation where an excluded path
      is relied on at a later point in the history for a branch, copy or merge
      action. If such a situation is found the paths are logged and the excluded
      <replaceable>source path</replaceable> is added to the
      <filename>issue.map</filename> file. To resolve the issue the exclusion
      should be removed from the <filename>exclude.map</filename> file or a
      regular expression, based on the <filename>issue.map</filename> file,
      added to the <filename>include.map</filename> file.
    </para>

    <para>
      For example; to exclude all Subversion tags in the folder 'tags/', create
      an exclusion map file <filename>exclude.map</filename>:
    </para>

<programlisting language="ini">
# exclude Subversion tags:
^tags/.*
</programlisting>

    <para>
      Then start the conversion to verify the map:
    </para>

<programlisting>
pallen-mac:main$ java -jar dist/p4convert.jar --config=Config/foo.cfg 
loading ChangeMap: 	changeMap.txt
loading TypeMap: 	types.map
importing revisions: 	1 to 20635 out of 20635
exclude.map: ^tags/.*
Verifying exclusion map...
issue: tags/rel-1.0.14/api
issue: tags/rel-1.0.14/sys
issue: tags/rel-2.0.3
Issues found, saving issue map...
Caught EXIT shutting down ...
</programlisting>

    <para>
      Looking at the reported issues the tags 'rel-1.0.14' and 'rel-2.0.3' have
      some actions that conflict with our exclusion, to resolve this simply add
      the exclusions to the 'include.map' file:
    </para>

<programlisting language="ini">
# issues reported for tags/ folder
^tags/rel-1.0.14/.*
^tags/rel-2.0.3/.*
</programlisting>
  </section>

  <section xml:id="config.labeling_subversion_paths">
    <title>Labeling Subversion Paths</title>
    
    <para>
      Whilst Subversion does not have a specific label entity may users follow 
      the 'tags' convention.  If a 'tag' path is pure (in that it has not had 
      subsequent changes to the content) it can be converted to a Perforce 
      label. 
    </para>

    <orderedlist>
    
      <listitem>
        
        <para>
          To enable labeling of Subversion tags, set the 
          <parameter>com.p4convert.svn.labels</parameter> to 
          <parameter>true</parameter> and define maps: 
          <filename>exclude.map</filename> and <filename>include.map</filename>.
        </para>

<programlisting language="ini">
com.p4convert.svn.labels=true
</programlisting>

      </listitem>
    
      <listitem>
      
        <para>
          The maps are designed with resect to branches.  The default behaviour is
          for all Subversion tag operations to be imported as Perforce branches. 
          In order to change the behaviour and attempt to import the Subversion tag
          as a Perforce label the path must be in the exclude map.      
        </para>
    
        <para>
          For example; to import all Subversion tags in the folder 'tags/' as 
          Perforce labels, create an exclusion map file
          <filename>exclude.map</filename>:
        </para>

<programlisting language="ini">
# exclude Subversion tags:
^tags/.*
</programlisting>

      </listitem>
      
      <listitem>

        <para>
          A Perforce label will need a unique name space derived from the 'tags'
          path.  The conversion tool provides a depth and regular expression 
          configuration option to assist.
        </para>    
        
<programlisting language="ini">
com.p4convert.svn.labelFormat=svn_label:{depth}
</programlisting>  

<programlisting language="ini">
com.p4convert.svn.labelDepth=2
</programlisting>

        <para>
          The depth determins how much of the path to use for the unique label 
          name.  Typically a value of '2' for convertional Subversion usage. 
          With a depth of '2' the first two elements of the 'tags' path are then
          held in an array and used by a regular expression to generate the label
          name.
        </para>
        
        <para>
          For example, given a Subversion tag located <filename>tags/1.0.0/</filename>
          the following regular expressions provide the coresponding label names:
        </para>
    
<programlisting language="ini">
com.p4convert.svn.labelFormat=label:{2}         label:1.0.0
com.p4convert.svn.labelFormat={1}-{2}           tags-1.0.0
</programlisting>

        <note>
          <para>
            An empty expression will use the original path.
          </para>
        </note> 

<programlisting language="ini">
com.p4convert.svn.labelFormat=                  tags/1.0.0/
</programlisting>

        <note>
          <para>
            If a keyword of <parameter>{depth}</parameter> is used it will be 
            substituted with it's value.
          </para>
        </note> 

<programlisting language="ini">
com.p4convert.svn.labelFormat=label_{depth}     label_1.0.0
</programlisting>

      </listitem>
    </orderedlist>
     
  </section>

  <section xml:id="config.changelist_offset_options">
    <title>Changelist Offset options</title>

    <orderedlist>
      <listitem>
        <para>
          The default offset is <literal>0</literal> (i.e. not offsetting).
          Offset is currently available for Convert Mode and allows subversion
          revisions to be converted into Perforce changelists by a fixed offset:
        </para>

<programlisting language="ini">
com.p4convert.p4.offset=0
</programlisting>
      </listitem>

      <listitem>
        <para>
          After the conversion a <emphasis>changeMap</emphasis> file is appended
          locally containing a Subversion revision number to Perforce
          change-list mapping. The file name is configured by the option:
        </para>

<programlisting language="ini">
com.p4convert.log.changeMap=changeMap.txt
</programlisting>

        <para>
          A changemap looks like this:
        </para>

<programlisting language="ini">
# &lt;Change&gt;, &lt;SVN revision&gt;	
1, 1
2, 2
3, 3
...
</programlisting>
      </listitem>
    </orderedlist>
  </section>

  <section xml:id="config.unicode_support">
    <title>Unicode Support</title>

    <para>
      The following Unicode enable options apply to Unicode support for Import
      Mode and Convert Mode. The Charset options are only applicable to Import
      Mode, when translating a file through the Perforce client. In Convert Mode
      archive files are always written in UTF-8 for a Unicode enabled Perforce
      server.
    </para>

    <para>
      Defaults (for non-Unicode servers):
    </para>

<programlisting language="ini">
com.p4convert.p4.unicode=false
com.p4convert.p4.translate=true
com.p4convert.p4.charset=&lt;none&gt;
</programlisting>

    <para>
      In some situations it is preferable to import text files as-is (untranslated).
      Typically this is true for a non-unicode environment where all the user are on
      Windows clients.  To disable translation set the following option to
      <parameter>false</parameter>.
    </para>

<programlisting language="ini">
com.p4convert.p4.translate=false
</programlisting>

    <para>
      When translation is disabled high-ascii text uses the content type
      <parameter>TEXT-RAW</parameter> and the following warning is disabled:
    </para>
    
<programlisting language="ini">
... Non-unicode server, downgrading file to text
</programlisting>

    <para>
      Recommended configuration for a Unicode conversion:
    </para>

<programlisting language="ini">
com.p4convert.p4.unicode=true
com.p4convert.p4.translate=true
com.p4convert.p4.charset=utf8
</programlisting>

    <para>
      For Unicode conversions set the JVM arg:
    </para>

<programlisting language="ini">
-Dfile.encoding=UTF-8
</programlisting>

    <para>
      Some Solaris and Linux conversions may need the locale set:
    </para>

<programlisting language="bash">
export LC_ALL=en_GB.UTF-8 
</programlisting>

    <para>
      Once a Perforce server is switched to Unicode enabled mode
      (<parameter>-xi</parameter>), all client workspaces need to define a
      character set. For details see:
    </para>

    <para>
      <link xlink:href="http://answers.perforce.com/articles/KB_Article/Internationalization-and-Localization">http://answers.perforce.com/articles/KB_Article/Internationalization-and-Localization</link>
    </para>

    <note>
      <para>
        A non-Unicode enabled Perforce Server will accept UTF16 files.
      </para>
    </note>

    <section xml:id="config.unicode_support.normalization">
      <title>Normalisation</title>

      <para>
        Platform Unicode normalisation is detected when the configuration file
        is generated, however it can be changed by setting the following
        configuration option to <literal>NFC</literal> or
        <literal>NFD</literal>:
      </para>

<programlisting language="ini">
com.p4convert.p4.normalisation=NFD
</programlisting>

      <para>
        The default detection is based on the following:
      </para>

      <informaltable>
        <tgroup cols="2">
          <colspec colname="platform" colwidth="*"/>
          <colspec colname="normalization" colwidth="*"/>
          <thead>
            <row>
              <entry><para>Platform</para></entry>
              <entry><para>Normalization</para></entry>
            </row>
          </thead>

          <tbody>
            <row>
              <entry><para>Windows</para></entry>
              <entry><para><literal>NFC</literal></para></entry>
            </row>

            <row>
              <entry><para>Mac</para></entry>
              <entry><para><literal>NFD</literal></para></entry>
            </row>

            <row>
              <entry><para>*nix/*nux</para></entry>
              <entry><para><literal>NFC</literal></para></entry>
            </row>

            <row>
              <entry><para>Sun</para></entry>
              <entry><para><literal>NFC</literal></para></entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>
    </section>

    <section xml:id="config.unicode_support.subversion_properties">
      <title>Subversion Properties</title>

      <para>
        By default, the converter parses Subversion properties as UTF-8 strings.
        The conversion uses properties such as <literal>svn:log</literal>,
        <literal>svn:author</literal> for attributes in Perforce and must decode
        the byte sequence to UTF-8. In some data sets Windows users may have
        added high ASCII characters in one or more code pages. This release now
        supports a configuration option:
      </para>

<programlisting language="ini">
com.p4convert.svn.propTextType=UNKNOWN
</programlisting>

      <para>
        The following strings denote the supported char-sets:
      </para>

      <simplelist type="vert" columns="4">
        <member>Big5</member>
        <member>BINARY</member>
        <member>EUC-JP</member>
        <member>EUC-KR</member>
        <member>GB18030</member>
        <member>IBM420_ltr</member>
        <member>IBM420_rtl</member>
        <member>IBM424_ltr</member>
        <member>IBM424_rtl</member>
        <member>ISO-2022-CN</member>
        <member>ISO-2022-JP</member>
        <member>ISO-2022-KR</member>
        <member>ISO-8859-1</member>
        <member>ISO-8859-2</member>
        <member>ISO-8859-5</member>
        <member>ISO-8859-6</member>
        <member>ISO-8859-7</member>
        <member>ISO-8859-8</member>
        <member>ISO-8859-9</member>
        <member>KOI8-R</member>
        <member>Shift_JIS</member>
        <member>UNKNOWN</member>
        <member>US-ASCII</member>
        <member>UTF-16BE</member>
        <member>UTF-16LE</member>
        <member>UTF-32BE</member>
        <member>UTF-32LE</member>
        <member>UTF-8</member>
        <member>windows-1251</member>
        <member>windows-1252</member>
        <member>windows-1254</member>
        <member>windows-1256</member>
      </simplelist>

      <para>
        The first scan is always <literal>UTF-8</literal> followed by the
        configuration option. <literal>BINARY</literal> implies a skip and the
        string <literal>&lt;binary property&gt;</literal> is inserted.
      </para>
    </section>
  </section>

  <section xml:id="config.advanced">
    <title>Advanced Configuration</title>

    <section xml:id="config.advanced.directory_properties">
      <title>Directory Properties</title>

      <para>
        The following options allow Subversion Directory Properties to be stored
        as versioned files in Perforce. To enable this mode set the following
        property to <literal>true</literal>:
      </para>

<programlisting language="ini">
com.p4convert.svn.propEnabled=true
</programlisting>

      <para>
        To select the property name and format: (Note: only
        <literal>ini</literal> mode is supported)
      </para>

<programlisting language="ini">
com.p4convert.svn.propEncoding=ini
com.p4convert.svn.propName=.svn.properties
</programlisting>
    </section>

    <section xml:id="config.advanced.empty_changelists">
      <title>Empty changelists</title>

      <para>
        The following property will attempt to skip empty changes (where the
        change contains no revisions). This is typically the default behavior of
        the client or Import Mode, so it is only really used in Convert Mode.
      </para>

<programlisting language="ini">
com.p4convert.p4.skipEmpty=false
</programlisting>
    </section>

    <section xml:id="config.advanced.username_translation">
      <title>Username translation</title>

      <para>
        A username map file (<filename>users.map</filename>) can be generated
        using the <parameter>--users</parameter> option and then the
        right-hand-side modified with the new user name. The rename will only
        occur if the conversion tool finds the <filename>users.map</filename>
        file in the current working directory.
        Username mapping is not currently supported for CVS conversions.
      </para>
    </section>

    <section xml:id="config.advanced.binary_file_detection">
      <title>Binary file detection</title>

      <para>
        Binary files can be identified by adding their extensions to the type
        map file <filename>types.map</filename>. The format is based on Perforce
        typemap spec, however it is limited to paths of the form
        <filename>//...<replaceable>.ext</replaceable></filename> (where
        <replaceable>.ext</replaceable> is the binary extension).
      </para>

      <para>
        Default Type map (<filename>types.map</filename>):
      </para>

<programlisting>
TypeMap:
        binary	//....zip
        binary	//....gif
        binary	//....png
        binary	//....jpg
        binary  //....dll
        binary  //....class
        binary  //....jar
        binary  //....ecsfr
</programlisting>

      <para>
        Modification bits (<literal>+mxwlk</literal>) are supported and can be
        added using the type mapping. Binary detection though the type map is
        recommended as conversion is much faster. Binary files not identified in
        the type map will be scanned by the ICU4J libraries and if no
        text/Unicode match is found they are assumed to be binary.
      </para>

      <warning>
        <para>
          ICU4J may incorrectly identify small binary files as text creating
          sync issues on Windows clients.
        </para>
      </warning>
    </section>

    <section xml:id="config.advanced.changelist_description_format">
      <title>Changelist Description Format</title>

      <para>
        The <parameter>logRevID</parameter> option can be used to reformat the
        Subversion revision descriptions to include the revision ID using the
        template:
      </para>

      <itemizedlist>
        <listitem>
          <para>
            <replaceable>&lt;rev&gt;</replaceable> substituted with the
            Subversion revision
          </para>
        </listitem>

        <listitem>
          <para>
            <replaceable>&lt;description&gt;</replaceable> substituted with the
            Subversion log
          </para>
        </listitem>
      </itemizedlist>

      <para>
        The default value (as-is):
      </para>
      
<programlisting language="ini">
com.p4convert.p4.logRevID=&lt;description&gt;
</programlisting>
    </section>

    <section xml:id="config.advanced.case_sensitivity">
      <title>Case Sensitivity</title>

      <para>
        The platform case sensitivity is detected when generating the
        configuration file. There is normally no reason to change this behavior
        from the detected defaults. Conversions between different platforms
        should be avoided especially when converting from a case sensitive
        environment (such as Linux) to a case insensitive environment (such as
        Windows). The advanced case handling options supported are set using one
        of the following options:
      </para>

<programlisting language="ini">
com.p4convert.p4.caseMode=FIRST
</programlisting>

      <itemizedlist>
        <listitem>
          <para>
            <literal>NONE</literal> - treat all paths as case sensitive (Linux).
          </para>
        </listitem>

        <listitem>
          <para>
            <literal>LOWER</literal> - convert all paths to lower case
          </para>
        </listitem>

        <listitem>
          <para>
            <literal>UPPER</literal> - convert all paths to upper case
          </para>
        </listitem>

        <listitem>
          <para>
            <literal>FIRST</literal> - use the first encountered case
            combination (Windows)
          </para>
        </listitem>
      </itemizedlist>

      <para>
        When using Convert Mode the generated Perforce archive files are
        based on the platform's case sensitivity. However on Linux platforms it
        can be useful to store archive files as if on a case-insensitive server
        (<command>p4d -C1</command>). This can be simulated by setting the following
        option to <literal>true</literal>:
      </para>

<programlisting language="ini">
com.p4convert.p4.lowerCase=true
</programlisting>

      <important>
        <para>
          If this option is set the path to the Perforce root directory, defined
          by <parameter>com.p4convert.adv.p4root</parameter>, must be in
          <emphasis role="bold">lower case</emphasis> and the case mode of
          <literal>FIRST</literal> must be used.
        </para>
      </important>
    </section>

    <section xml:id="config.advanced.rcs_keyword_expansion">
      <title>RCS Keyword expansion (<literal>svn:keywords</literal>)</title>

      <para>
        By default, RCS keyword expansion attributes are imported; however
        setting the configuration option:
      </para>

<programlisting language="ini">
com.p4convert.svn.keepKeyword=true
</programlisting>

      <para>
        Setting a value of <literal>false</literal> will ignore all previous
        keyword attributes and import the files as normal text. See
        <link linkend="notes.keyword_expansion_issues">keyword notes</link> for
        known issues.
      </para>
    </section>

    <section xml:id="config.advanced.merge_information">
      <title>Merge Information (<literal>svn:mergeinfo</literal>)</title>

      <para>
        Supports Subversion 1.5-1.7 merge information and calculates the
        corresponding Perforce integration credit for the various actions. The
        feature is not enabled by default and if required the following
        configuration option must be set to true:
      </para>

<programlisting language="ini">
com.p4convert.svn.mergeInfoEnabled=true
</programlisting>
    </section>
  </section>
</chapter>
  <!-- vim: set ts=2 sw=2 tw=80 ai si: --><?xml-model href="http://www.oasis-open.org/docbook/xml/5.0/rng/docbookxi.rng" schematypens="http://relaxng.org/ns/structure/1.0"?><?xml-model href="http://www.oasis-open.org/docbook/xml/5.0/rng/docbook.rng" type="application/xml" schematypens="http://purl.oclc.org/dsdl/schematron"?><chapter xml:id="chapter.running" version="5.0" xml:base="03_running.xml">
  <title>Running P4Convert</title>

  <section xml:id="running.import_mode">
    <title>Import Mode</title>

    <para>
      Import Mode will pull in file revisions from a Subversion dump file or CVS repository,
      adding them to the Perforce Server specified by the connection details in the
      configuration options. To use this mode set:
    </para>

<programlisting language="ini">
com.p4convert.p4.mode=IMPORT
</programlisting>

    <para>
      Care should be taken when adding data to a pre-existing Perforce Server
      that the revision actions do not conflict with revisions already in the
      Perforce Server; typically, this can occur if the Server has been in-use
      since the previous migration.
    </para>

    <para>
      To avoid such scenarios the import should either be to a unique depot, to
      avoid conflict, or the Perforce Server should be Read Only during
      subsequent migrations. After a conversion is complete, it is possible to
      merge the new data with an existing depot using tools like
      <application>PerfMerge++</application>.
    </para>

    <para>
      The converter will check that your Perforce Server has no pending changes,
      and will abort a conversion if any are detected.
    </para>

    <section xml:id="running.import_mode.configuration">
      <title>Configuration options specific to Import Mode</title>

      <orderedlist>
        <listitem>
          <para>
            Perforce server address and port (escape the '<literal>:</literal>'
            with '<literal>\:</literal>'):
          </para>
<programlisting language="ini">
com.p4convert.p4.port=<replaceable>localhost\:4444</replaceable>
</programlisting>
        </listitem>

        <listitem>
          <para>
            Default user and client for server connection:
          </para>

<programlisting language="ini">
com.p4convert.p4.client=<replaceable>p4-client</replaceable>
com.p4convert.p4.user=<replaceable>p4-user</replaceable>
</programlisting>
        </listitem>

        <listitem>
          <para>
            Client workspace root used to import files into Perforce:
          </para>

<programlisting language="ini">
com.p4convert.p4.clientRoot=<replaceable>/Users/bruno/ws/</replaceable>
</programlisting>
        </listitem>

        <listitem>
          <para>
            If Security is set to level 1 or greater, then the
            <replaceable>p4-user</replaceable> must have
            <emphasis>admin</emphasis> permissions in the Protection table and
            the password supplied as a string (the
            default is set to <envar>ws/</envar> under your local directory):
          </para>

<programlisting language="ini">
com.p4convert.p4.passwd=<replaceable>PaSSwoRd</replaceable>
</programlisting>
        </listitem>

        <listitem>
          <para>
            Alternatively if the user is already logged in and there is a valid
            ticket, then leave the password field unset and set your environment
            for <envar>P4TICKETS</envar> (don't rely on the
            <envar>P4TICKETS</envar> unset default as <command>p4-java</command>
            will not find your ticket file).
          </para>
        </listitem>
      </orderedlist>
      
      <warning>
        <para>
          For long running conversions where authentication is required, please
          insure that the conversion user has an "Unlimited" login timeout.
        </para>
      </warning>
    </section>
  </section>

  <section xml:id="running.convert_mode">
    <title>Convert Mode</title>

    <para>
      Convert Mode is more advanced and requires knowledge of the Perforce
      Journal replay and Archive file store. This mode can only be used for
      single shot conversions and cannot be used incrementally. The performance
      of Convert Mode is significantly better than Import Mode (x100
      sometimes!).
    </para>

    <para>
      After using Convert Mode the administrator will need to run
      several commands to rebuild the Perforce server and upgrade the
      metadata. Please refer to the <xref linkend="running.post_conversion"/>
      section for step-by-step instructions.
    </para>

    <para>
      To use this mode set:
    </para>
        
<programlisting language="ini">
com.p4convert.p4.mode=CONVERT
</programlisting>

    <section xml:id="running.convert_mode.configuration">
      <title>Configuration options specific to Conversion Mode</title>

      <orderedlist>
        <listitem>
          <para>
            Perforce server root address (path should end with a
            slash (<literal>/</literal>)), the default is set to 
            <envar>p4_root/</envar> under you local directory:
          </para>

<programlisting language="ini">
com.p4convert.p4.root=<replaceable>/full/path/to/p4_root/</replaceable>
</programlisting>
        </listitem>

        <listitem>
          <para>
            Change list offset from which to start conversion (handy for batched conversions):
          </para>

<programlisting language="ini">
com.p4convert.p4.offset=<replaceable>0</replaceable>
</programlisting>
        </listitem>

        <listitem>
          <para>
            Generated journal names (useful to increment the prefix when running
            batched conversions):
          </para>

<programlisting language="ini">
com.p4convert.p4.jnlIndex=<replaceable>0</replaceable>
com.p4convert.p4.jnlPrefix=<replaceable>jnl.</replaceable>
</programlisting>
        </listitem>

        <listitem>
          <para>
            Mimic the 2011.1 or greater credit behavior on rollbacks /
            downgrades (to enable set value to <literal>true</literal>):
          </para>

<programlisting language="ini">
com.p4convert.p4.downgrade=<replaceable>false</replaceable>
</programlisting>
        </listitem>

        <listitem>
          <para>
            Perforce normalises line-endings when storing the file on the server
            and restores them based on the client workspace options and platform
            type. However, in special cases it can be useful to store
            line-ending in the server and use the 'share' option in the client.
            To disable normal line-ending support set the following option to
            <literal>false</literal>:
          </para>

<programlisting language="ini">
com.p4convert.p4.lineEnding=<replaceable>true</replaceable>
</programlisting>
        </listitem>

        <listitem>
          <para>
            For non Unicode servers, or to simplify storage of hi-ASCII files,
            setting the following option to <literal>false</literal> will store the file
            as <literal>binary</literal>:
          </para>

<programlisting language="ini">
com.p4convert.p4.unicode=<replaceable>false</replaceable>
</programlisting>
        </listitem>
      </orderedlist>
    </section>
  </section>

  <section xml:id="running.post_conversion">
    <title>Post Conversion [Conversion Mode]</title>

    <para>
      To finish a Convert Mode conversion you will need to install <command>p4</command>
      and <command>p4d</command> and run a few Perforce commands.
    </para>

    <orderedlist>
      <listitem xml:id="running.post_conversion.step1">
        <para>
          <emphasis role="bold">[Required]</emphasis> Change directory to
          <envar>P4ROOT</envar>, check there are no <filename>db.*</filename>
          files present and then replay the journal file(s):
        </para>

<screen>
$ cd p4_root
$ p4d -r . -jr jnl.0
Perforce db files in '.' will be created if missing...
Recovering from jnl.0...
Perforce server info:
	Server version 33 is replaying a version 0 journal/checkpoint.
</screen>

        <note>
          <para>
            The Server version is set to <literal>0</literal> to remind the
            administrator that an upgrade is required, see
            <link linkend="running.post_conversion.step3">step 3</link>.
          </para>
        </note>
      </listitem>

      <listitem xml:id="running.post_conversion.step2">
        <para>
          or, for multiple journal files:
        </para>

<programlisting>
$ p4d -r . -jr jnl.0 jnl.1 ....
</programlisting>

        <para>
          and with nohup:
        </para>

<programlisting>
nohup p4d -r . -jr jnl.0 jnl.1 .... &amp;
</programlisting>
      </listitem>

      <listitem xml:id="running.post_conversion.step3">
        <para>
          <emphasis role="bold">[Required]</emphasis> Upgrade the database from
          2004.2 schema. For simplicity the conversion generates a database
          using an old schema, allowing you to upgrade to a Perforce Server
          version of your choice. From the <envar>P4ROOT</envar> directory run
          the upgrade command:
        </para>

<screen>
$ p4d -r . -xu
Perforce db files in '.' will be created if missing...
2001.1: splitting db.integ into db.integed/db.resolve.
2001.1: splitting db.have into db.have and db.label.
2002.1: splitting pending db.change into db.changex.
2002.2: upgrading tempobj filetype in db.rev.
2002.2: upgrading tempobj filetype in db.working.
2003.1: initialize default depot.
2003.2: upgrading db.user.
2005.1: building db.revhx (headrev) table.
2005.1: building db.locks from db.working.
2005.2: building db.revdx (delrev) table.
2005.2: moving spec depot entries into db.revsx.
2007.3: (re)building haveMap from db.have/db.working.
2007.3: (re)building db.archmap (lazy-copy map) table.
2007.3: removing old db.archive.
2008.1: upgrading db.change.
2009.2: moving db.boddate/db.ixdate into db.bodtext/db.ixtext.
2009.2: removing db.boddate/db.ixdate.
2010.2: adding db.config.
2011.1: upgrading tiny.db.
...upgrades done
</screen>
      </listitem>

      <listitem xml:id="running.post_conversion.step4">
        <para>
          [Optional] If the conversion was run in Unicode mode (where
          <code>com.p4convert.p4.unicode=true</code>) and users are going to
          continue to add Unicode content then you may wish to set the server to
          Unicode mode. To enable Unicode run the following command from the
          P4ROOT directory:
        </para>

<programlisting language="bash">
$ p4d -r . -xi
</programlisting>
      </listitem>

      <listitem xml:id="running.post_conversion.step5">
        <para>
          [Alternative] If you are running your Perforce Server on Linux and
          your user base is predominantly Windows you may wish to force the
          server to run as case insensitive (only allowing one version of case
          for paths and files). The conversion option
          <code>com.p4convert.adv.lowerCase=true</code> will have been used with
          the case mode set to <code>com.p4convert.adv.caseMode=FIRST</code>.
          All p4d commands must be include the <parameter>-C1</parameter> flag,
          this includes the earlier
          <link linkend="running.post_conversion.step1">step 1</link> and
          <link linkend="running.post_conversion.step2">step 2</link>.
        </para>

        <para>
          For example:
        </para>

<programlisting language="bash">
$ cd p4_root
$ p4d -C1 -r . -jr jnl.0
$ p4d -C1 -r . -xu
</programlisting>
      </listitem>

      <listitem xml:id="running.post_conversion.step6">
        <para>
          [Recommended] Some archive files may not have MD5 sum digests
          (typically where Subversion did not store the digest or the digest
          does not match due to the use of keyword expansion). To fill in the
          metadata for MD5 sum digests and archive file sizes use the verify
          command (this might be best split into depots and sub directories for
          large servers):
        </para>

<programlisting language="bash">
$ p4 verify -u //...
</programlisting>
      </listitem>
    </orderedlist>
  </section>
</chapter>
  <!-- vim: set ts=2 sw=2 tw=80 ai si: --><?xml-model href="http://www.oasis-open.org/docbook/xml/5.0/rng/docbookxi.rng" schematypens="http://relaxng.org/ns/structure/1.0"?><?xml-model href="http://www.oasis-open.org/docbook/xml/5.0/rng/docbook.rng" type="application/xml" schematypens="http://purl.oclc.org/dsdl/schematron"?><chapter xml:id="chapter.notes" version="5.0" xml:base="04_notes.xml">
  <title>Notes</title>

  <section xml:id="notes.keyword_expansion_issues">
    <title>Keyword Expansion Issues:</title>

    <para>
      The conversion process preserves keyword file types and sets these files
      in Perforce with the +k modifier. However keywords in Subversion and
      Perforce are expanded differently. For example: In Subversion the keyword
      <literal>$Revision$</literal> expands to:
    </para>

<screen>
$Revision: 25005 $		(a change number in Perforce)
</screen>

    <para>
      Another example is the keyword <literal>$Date$</literal>, which in
      Subversion gives you the time as well...
    </para>

<screen>
$Date: 2006-02-17 12:09:10 +0000 (Fri, 17 Feb 2006) $
</screen>

    <para>
      and in Perforce...
    </para>

<screen>
$Date: 2006/02/17 $
</screen>

    <para>
      Here is a list of alternatives, (based on the above example):
    </para>

<screen>
$Revision$    ==&gt; $Change$	gives	$Change: 25005 $
$Date$        ==&gt; $DateTime$	gives	$DateTime: 2006/02/17 12:09:10 $
</screen>

    <para>
      Due to the differences in keyword expansion the MD5 sum in Subversion is
      not valid for use in Perforce. This is why any keyword expanded files have
      an empty MD5 sum and why the <command>p4 verify -u //...</command> command
      is recommended in the 'Optional Steps' section.
    </para>
  </section>

  <section xml:id="notes.verification">
    <title>Verification</title>

    <para>
      Verification can be performed using a running Subversion server and
      comparing the differences in files in Perforce using the audit log. To
      enable the audit log set the following option to <literal>true</literal>
      and choose the file name.
    </para>

<programlisting language="ini">
com.p4convert.log.audit.enabled=true
com.p4convert.log.audit.filename=audit.log
</programlisting>

    <para>
      A sample line of the audit log:
    </para>

<screen>
# &lt;SVN path&gt;, &lt;SVN revision&gt;, &lt;P4 change&gt;, &lt;MD5 sum&gt;
trunk/src/foo.c, 1, 1, 1234567890abcdef1234567890abcdef
</screen>
  </section>

  <section xml:id="notes.output">
    <title>Output and Logs</title>

    <section xml:id="notes.output.console">
      <title>Console output and logging configuration options</title>

      <para>
        The default SLF4J logging options can be overwritten with another
        configuration file; specify the
        <parameter>log4j.configuration</parameter> option with a local file,
        using the syntax:
      </para>

      <para>
        <literal>file:<replaceable>your_local_file</replaceable></literal>
      </para>

<programlisting language="bash">
java -Dlog4j.configuration=file:log4j.xml -jar p4convert.jar
</programlisting>

      <para>
        Please use or refer to the sample <filename>debug.log4j.xml</filename>
        for logging options.
      </para>
    </section>

    <section xml:id="notes.output.future">
      <title>
        These options are reserved for testing or future enhancements:
      </title>

<programlisting language="ini">
com.p4convert.core.test
com.p4convert.core.version
com.p4convert.svn.emptyDirEnabled
com.p4convert.svn.emptyDirName
</programlisting>
    </section>

    <section xml:id="notes.output.reading">
      <title>Reading Console/Logging output</title>

<screen>
Importing Subversion ranges:

start: 1 
end:   23091
last:  23091
		
1.0 A:D - trunk
1.1 A:D - trunk/src
1.2 A:F - trunk/src/foo.c (UTF-8)
mapping: r1 =&gt; @1
		
2.0 A:F - trunk/src/bar.png (BINARY)
mapping: r2 =&gt; @2
...
</screen>

      <para>
        Explanation of output lines, for example:
      </para>
      
<screen>
1.2 A:F - trunk/src/foo.c (UTF-8)</screen>

      <para>
        The numbering <literal>1.2</literal> refers to the current Subversion
        revision and the node action. (<literal>1</literal> Subversion revision
        1 and <literal>.2</literal> = the third node action
        as <literal>.0</literal> would be the first index)
      </para>

      <para>
        The letters <literal>A:F</literal> refers to the Subversion action and
        if it is a file or directory operation.
      </para>

      <itemizedlist>
        <listitem>
          <para>
            A Add
          </para>
        </listitem>

        <listitem>
          <para>
            B Branch
          </para>
        </listitem>

        <listitem>
          <para>
            E Edit
          </para>
        </listitem>

        <listitem>
          <para>
            I Integrate (merge fromNode)
          </para>
        </listitem>

        <listitem>
          <para>
            M Merge (svn:mergeinfo)
          </para>
        </listitem>

        <listitem>
          <para>
            C Copy (svn replace action with fromNode)
          </para>
        </listitem>

        <listitem>
          <para>
            U Update (svn replace action)
          </para>
        </listitem>

        <listitem>
          <para>
            R Remove (delete)
          </para>
        </listitem>

        <listitem>
          <para>
            F File
          </para>
        </listitem>

        <listitem>
          <para>
            D Directory
          </para>
        </listitem>
      </itemizedlist>

      <para>
        The subversion path <filename>trunk/src/foo.c</filename> is followed by
        the detected type.
      </para>

      <informaltable>
        <tgroup cols="2">
          <colspec colname="detected_type" colwidth="*"/>
          <colspec colname="perforce_type" colwidth="*"/>
          <thead>
            <row>
              <entry>
                <para>
                  Detected Type
                </para>
              </entry>

              <entry>
                <para>
                  Perforce Base Type
                </para>
              </entry>
            </row>
          </thead>

          <tbody>
            <row>
              <entry>
                <para>
                  UTF-8
                </para>
              </entry>

              <entry>
                <para>
                  Unicode
                </para>
              </entry>
            </row>

            <row>
              <entry>
                <para>
                  UTF-16BE
                </para>
              </entry>

              <entry>
                <para>
                  utf16
                </para>
              </entry>
            </row>

            <row>
              <entry>
                <para>
                  UTF-16LE
                </para>
              </entry>

              <entry>
                <para>
                  utf16
                </para>
              </entry>
            </row>

            <row>
              <entry>
                <para>
                  UTF-32BE
                </para>
              </entry>

              <entry>
                <para>
                  Unicode
                </para>
              </entry>
            </row>

            <row>
              <entry>
                <para>
                  UTF-32LE
                </para>
              </entry>

              <entry>
                <para>
                  Unicode
                </para>
              </entry>
            </row>

            <row>
              <entry>
                <para>
                  Shift_JIS
                </para>
              </entry>

              <entry>
                <para>
                  Unicode
                </para>
              </entry>
            </row>

            <row>
              <entry>
                <para>
                  ISO-2022-JP
                </para>
              </entry>

              <entry>
                <para>
                  downgraded to binary
                </para>
              </entry>
            </row>

            <row>
              <entry>
                <para>
                  ISO-2022-CN
                </para>
              </entry>

              <entry>
                <para>
                  downgraded to binary
                </para>
              </entry>
            </row>

            <row>
              <entry>
                <para>
                  ISO-2022-KR
                </para>
              </entry>

              <entry>
                <para>
                  downgraded to binary
                </para>
              </entry>
            </row>

            <row>
              <entry>
                <para>
                  GB18030
                </para>
              </entry>

              <entry>
                <para>
                  Unicode
                </para>
              </entry>
            </row>

            <row>
              <entry>
                <para>
                  EUC-JP
                </para>
              </entry>

              <entry>
                <para>
                  Unicode
                </para>
              </entry>
            </row>

            <row>
              <entry>
                <para>
                  EUC-KR
                </para>
              </entry>

              <entry>
                <para>
                  Unicode
                </para>
              </entry>
            </row>

            <row>
              <entry>
                <para>
                  Big5
                </para>
              </entry>

              <entry>
                <para>
                  Unicode
                </para>
              </entry>
            </row>

            <row>
              <entry>
                <para>
                  ISO-8859-1
                </para>
              </entry>

              <entry>
                <para>
                  Unicode
                </para>
              </entry>
            </row>

            <row>
              <entry>
                <para>
                  ISO-8859-2
                </para>
              </entry>

              <entry>
                <para>
                  Unicode
                </para>
              </entry>
            </row>

            <row>
              <entry>
                <para>
                  ISO-8859-5
                </para>
              </entry>

              <entry>
                <para>
                  Unicode
                </para>
              </entry>
            </row>

            <row>
              <entry>
                <para>
                  ISO-8859-6
                </para>
              </entry>

              <entry>
                <para>
                  downgraded to binary
                </para>
              </entry>
            </row>

            <row>
              <entry>
                <para>
                  ISO-8859-7
                </para>
              </entry>

              <entry>
                <para>
                  Unicode
                </para>
              </entry>
            </row>

            <row>
              <entry>
                <para>
                  ISO-8859-8
                </para>
              </entry>

              <entry>
                <para>
                  Unicode
                </para>
              </entry>
            </row>

            <row>
              <entry>
                <para>
                  windows-1251
                </para>
              </entry>

              <entry>
                <para>
                  Unicode
                </para>
              </entry>
            </row>

            <row>
              <entry>
                <para>
                  windows-1254
                </para>
              </entry>

              <entry>
                <para>
                  Unicode
                </para>
              </entry>
            </row>

            <row>
              <entry>
                <para>
                  windows-1256
                </para>
              </entry>

              <entry>
                <para>
                  downgraded to binary
                </para>
              </entry>
            </row>

            <row>
              <entry>
                <para>
                  KOI8-R
                </para>
              </entry>

              <entry>
                <para>
                  Unicode
                </para>
              </entry>
            </row>

            <row>
              <entry>
                <para>
                  ISO-8859-9
                </para>
              </entry>

              <entry>
                <para>
                  Unicode
                </para>
              </entry>
            </row>

            <row>
              <entry>
                <para>
                  IBM424_rtl
                </para>
              </entry>

              <entry>
                <para>
                  downgraded to binary
                </para>
              </entry>
            </row>

            <row>
              <entry>
                <para>
                  IBM424_ltr
                </para>
              </entry>

              <entry>
                <para>
                  downgraded to binary
                </para>
              </entry>
            </row>

            <row>
              <entry>
                <para>
                  IBM420_rtl
                </para>
              </entry>

              <entry>
                <para>
                  downgraded to binary
                </para>
              </entry>
            </row>

            <row>
              <entry>
                <para>
                  IBM420_ltr
                </para>
              </entry>

              <entry>
                <para>
                  downgraded to binary
                </para>
              </entry>
            </row>

            <row>
              <entry>
                <para>
                  BINARY
                </para>
              </entry>

              <entry>
                <para>
                  binary
                </para>
              </entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>

      <note>
        <para>
          The detected type is based on language detection using ICU4J and not
          Subversion MIME or Perforce detection.
        </para>
      </note>

      <para>
        Finally <literal>mapping: r223 =&gt; @223</literal>' refers to the
        Subversion revision number (<literal>r223</literal>) to the Perforce
        changelist number (<literal>@223</literal>). Typically 1:1 unless offset
        or merged against an live or pre-existing Perforce Server.
      </para>
    </section>
  </section>

  <section xml:id="notes.errors">
    <title>Errors</title>

    <para>
      In Import Mode, Perforce related <command>p4-java</command> messages are
      reported as warnings and should be verified, for example:
    </para>

<screen>
46.3 A:F - repo/trunk/my.file
WARNING: p4java: //import/repo/trunk/my.file - file(s) up-to-date.
</screen>

    <para>
      In Conversion Mode, errors are reported as <emphasis>Panics</emphasis> and
      an exception is thrown.
    </para>

    <para>
      Problematic Subversion dump records can be extracted and sent to Perforce
      when it is not possible to send in the whole dumpfile. The extracted
      dumpfile only contains meta-data and the file content is removed and
      replaced with a block count.
    </para>

    <para>
      During an exception note the Subversion revision and node ID (the example
      above has a revision number of 46 and a node number of 3). Then run the
      following command to extract the problematic record, for example:
    </para>

<programlisting language="bash">
$ java -jar dist/p4convert.jar --type=SVN --repo=mysvndump.dump --extract=46.3  

searching for node: 46.3...
Node-path: repo/trunk/my.file
Node-kind: file
Node-action: add
Prop-content-length: 10
Text-content-length: 308
Text-content-md5: 6a339b6ccf2af72d77169ef29b98eb0b
Content-length: 318
      

PROPS-END
</programlisting>

    <para>
      A file is then generated called <filename>node.46.3.dump</filename> and
      will contain the Subversion record to be sent to Perforces, as well as the
      Subversion meta-data (everything after <literal>searching for node:
      46.3...</literal>).
    </para>
  </section>
</chapter>
</book>