<?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"?> <chapter xml:id="chapter.config" 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" > <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>--config</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 --config CVS </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>--config SVN</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>--config CVS</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> (Optionaly) 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.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> </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/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.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"> # <Change>, <SVN revision> 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.charset=<none> </programlisting> <para> A UTF8 client example: (for a full list see <command>p4 help charset</command>) </para> <programlisting language="ini"> com.p4convert.p4.unicode=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><binary property></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>><rev></replaceable> substituted with the Subversion revision </para> </listitem> <listitem> <para> <replaceable><description></replaceable> substituted with the Subversion log </para> </listitem> </itemizedlist> <para> The default value (as-is): </para> <programlisting language="ini"> com.p4convert.p4.logRevID=<description> </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>
# | Change | User | Description | Committed | |
---|---|---|---|---|---|
#1 | 10838 | Robert Cowham |
Populate //guest/robert_cowham/perforce/utils/p4convert/... from //guest/perforce_software/p4convert/.... |
||
//guest/perforce_software/p4convert/docs/xml/02_config.xml | |||||
#4 | 10795 | adrian_waters | Clarification re CVS vs SVN / tidy-up / fix typos / | ||
#3 | 10769 | Paul Allen |
Removed references to 'svn' from the name 'p4convert-svn'. Updated: Build, Usage, User docs, and Releases notes. |
||
#2 | 10698 | Paul Allen | Updates to the documentation for CVS and SVN configurations. | ||
#1 | 9809 | Paul Allen |
Documentation content. Will need to publish Perforce Documentation _build (Check if Open Source compatible). |