p4migrate Administrator Guide

Executive Summary

p4migrate helps Perforce Administrators produce a case-consistent checkpoint and optionally rename archive files so you can move servers between platforms and case modes safely. It uses a two-pass workflow with conflict maps (cmap, cmap2): first pass discovers case conflicts and generates cmap (report-only). You edit only the right-hand side (RHS) of cmap to choose preferred casing. Second pass applies your choices, writes an edited checkpoint, and appends any unresolved conflicts to cmap2.

Contents

Do I need p4migrate?

Quick Start (Two-Pass Workflow)

1. Create a checkpoint on the source server (e.g., p4 admin checkpoint).
2. First pass — Generate the conflict map (report-only):
   

   p4migrate -y -c cmap checkpoint.1

   Review cmap and edit only the RHS case to your preferred casing.
3. Second pass — Apply the map; produce edited checkpoint and cmap2:
   

   p4migrate -y -t cmap -c cmap2 -o checkpoint.edited checkpoint.1

   If cmap2 shows appended entries, fix your map (usually missing parent mappings or illegal edits), then rerun.
4. Archive renaming (if moving to case-sensitive and archives differ in case): run the rename phase to align archive paths to the edited checkpoint.
5. Verify line endings and content as appropriate (text vs binary), then bring up the target server.

Use Cases

1) Case-insensitive → Case-sensitive

Typical: Windows or macOS → Linux with a case-sensitive target. The checkpoint may contain case variants referring to the same logical item on case-insensitive platforms. p4migrate discovers these and creates a conflict map. You select the preferred casing (RHS). Second pass applies the changes and produces an edited checkpoint. If archives were written in lowercase or inconsistent casing, use the rename phase to align archive paths with the edited checkpoint.

2) Case-sensitive → Case-insensitive

Typical: Linux → Windows or macOS, or Linux with a case-insensitive target. Prefer p4d -C1 to switch case mode; p4migrate is generally not required to fix case since a case-insensitive server treats variants equivalently. Still review archive naming and paths for consistency. If you do use p4migrate for hygiene, follow the same two-pass workflow to standardize casing before the transition.

Conflict Maps: Generation and Editing

How p4migrate generates maps

• Scans all relevant checkpoint tables (paths in db.rev and related tables; domains; groups; other identifiers).
• Tracks alias variants for each logical item (e.g., //AcesFoxpro vs //ACESFoxpro).
• Generates cmap with one line per item having aliases; by default LHS == RHS using the most common alias.

Editing rules (RHS only)

• Allowed: change letter case on the RHS.
• Not allowed: rename, restructure, or add/remove characters; do not edit the LHS.
• Parent-first: put parent directory mappings above children; add mappings for any non-leaf directory whose case you change.

Examples

//depot/Main/...   //depot/main/...
//ACESFoxpro/...   //acesfoxpro/...
//Conversion/...   //conversion/...

Invalid:
//depot/Main/...   //depot/main         # Missing /...
//project/...      //proj/...           # Not a case-only change

Example: Adding a parent mapping when changing a leaf directory

Suppose the generated conflict map includes a mapping for a leaf directory where the conflict occurred:

//depot/QA/Gastar/... //depot/QA/Gastar/...

You edit the map to change the case of both the parent directory (QA) and the leaf directory (Gastar):

//depot/QA/Gastar/... //depot/qa/gastar/...

In this case, you must also add a new mapping for the parent directory to avoid introducing a new conflict for other //depot/QA/... paths outside the Gastar subdirectory:

//depot/QA/... //depot/qa/...
//depot/QA/Gastar/... //depot/qa/gastar/...

Second Pass and cmap2

• Applies your RHS choices to produce checkpoint.edited.
• Writes cmap2: your original (edited) map first, then the “added by p4migrate” section for any unresolved conflicts.
• If the appended section is empty (only comments), your map resolved all conflicts.

When conflicts remain after the second pass

• Review your cmap for illegal edits (non–case-only changes on RHS).
• Ensure parent mappings exist and precede their children.
• Add missing parent mappings for non-leaf directories whose case you changed.
• Keep casing consistent across the hierarchy; then rerun the second pass.

Archive File Conversion Issues

On Windows servers (2000.2+), archive directories/files may be stored in lowercase; on case-sensitive targets, archives must match the edited checkpoint paths exactly. Use p4migrate’s rename phase to correct archive casing and verify with sample file retrieval.

Renaming Archives Phase

After producing checkpoint.edited with your preferred casing, you must ensure that the archive file and directory names match the casing of paths in the checkpoint. On case-sensitive targets, mismatched archive names will prevent file retrieval.

Prerequisites

• Edited checkpoint (checkpoint.edited) is complete and validated.
• Conflict maps (cmap, cmap2) show no unresolved conflicts (or have been resolved).
• Target server case mode is set appropriately (e.g., case-sensitive).

Process Overview

1. Stop the Perforce server (p4d).
2. Run p4migrate with the -R option to rename archive directories/files to match checkpoint.edited casing. Provide -r <p4root> (required by -R) and -S <serverId> if needed.
3. Restart the server and validate with sample file operations.
4. Line ending conversion: More details here: Cross-Platform Helix Core Server Migration

Example Commands

# 1) Stop the server
p4 admin stop

# 2) Apply edited checkpoint (on the target server root)
p4d -r /path/to/p4root -jr checkpoint.edited

# 3) Rename archives to match the edited checkpoint casing using p4migrate
#    -R performs archive rename. -r supplies P4ROOT. -S may be required for server.depot.root configurations.
p4migrate -y -R -r /path/to/p4root -S MyServerId -t cmap -o checkpoint.edited checkpoint.1

# 4) Restart the server
p4d -r /path/to/p4root -p 1666

Tips and Validation

• Verify a sample of renamed paths: p4 print, p4 filelog, p4 sync on test clients.
• Log operations and keep migration records for audit.
• Be careful with binary files and LFS/graph depots; p4migrate renames paths, not contents.

For Windows/macOS (case-insensitive) sources moving to case-sensitive targets, archive renaming is commonly required because archives may be stored in lowercase or mixed case. For case-insensitive targets (p4d -C1), archive renaming is usually not necessary but consistency is still recommended.

Performance Considerations

• For multi-GB checkpoints, run on fast local storage (NVMe). Measure using /usr/bin/time -v.
• Translation maps are partitioned by path prefixes to keep lookups fast; short paths fall back to parent mappings when needed.
• Keep logs and review warnings like “Writing conflict map…” and “Success: all case-inconsistencies have been resolved.”

Command Sequences

First Pass

p4migrate -y -c cmap checkpoint

Edit cmap (RHS case-only)

Open cmap, adjust only the RHS casing; sort parent-before-child for readability.

Second Pass

p4migrate -y -t cmap -c cmap2 -o checkpoint.edited checkpoint

Rename Pass (Archives)

Rename archive directories/files to match the edited checkpoint casing (case-sensitive platforms):

# Provide P4ROOT and, if required, ServerId
p4migrate -y -R -r /path/to/p4root -S MyServerId -t cmap -o checkpoint.edited checkpoint

Usage and Options

Complete command-line usage for p4migrate:

  Usage: p4migrate [options] <checkpoint file>

  where options are:

    -c <filename>      - Filename to use for the output translation map,
                         also known as the 'conflict map'.

                         Conflicts in your checkpoint are recorded in this
                         file by generated mappings from the lowercase
                         variant of the filename to the most frequently
                         observed variant in your checkpoint. You should
                         edit this file and change the mappings to meet
                         your requirements and then supply the edited file
                         as the input translation map using the -t flag.

    -C0                - Generate a case sensitive checkpoint (default)

    -C1                - Generate a case insensitive checkpoint

    -j                 - Produce the output as a journal patch rather
                         than a replacement checkpoint.

    -l <filename>      - Filename to use for logfile. Defaults to stderr.

    -L <locale>        - The locale to use during the migration.
                         Not used if the source checkpoint is from a 'unicode' server.
                         The 'C' locale is set by default, and is the fastest for migrating,
                         but will not support case folding of multi-byte characters.
                         Any other locale may be specified, but it may slow down processing,
                         and will require that the specified locale is installed on the machine.
                         If the locale specified contains the string 'UTF-8' then utf8
                         case folding will be enabled.

    -o <filename>      - Filename to use for the output checkpoint.
                         After mapping records through the input translation
                         map, the edited records are written out to this
                         file. If no further conflicts remain, then this is
                         a case-consistent checkpoint. If conflicts remain
                         unresolved then this checkpoint should not be used
                         rebuild your database. You may pass '-' to use
                         stdout.

    -p <policy>        - Name of a built-in policy to apply. Valid policies
                         are:

                            lower    - convert all paths to lowercase
                            upper    - convert all paths to uppercase
                            head     - convert all paths to the variant used
                                       by the head revision

                         Note: The values for upper and lowercase characters
                         are very dependent on your locale. If your
                         checkpoint contains characters in different
                         character sets you should exercise great care with
                         the use of this option.

                         In particular, you should run 'p4 verify -q //...'
                         and check the output very carefully.

                         Note 2: Policies are applied before the translation
                         map, so you may override the policy for specific
                         paths using the translation map. You will likely
                         need several mappings to get this right. e.g.
                         with a policy of 'upper' you might use something
                         like this:

                             //depot/...          //Depot/...
                             //depot/main/...     //Depot/Main/...
                             //depot/main/www/... //Depot/Main/www/...

                         i.e. a mapping for every part of the tree that
                         you want to exempt from the policy


    -R                 - Attempt to rename the archive files to match the
                         case in the translated checkpoint. This option
                         is only available on case-sensitive platforms.

    -r <p4root>        - Your P4ROOT directory, this option may be needed if -R is used,
                         and the server.depot.root configurable is not found.

    -s                 - Will convert the input checkpoint to
                         'standard checkpoint' format.

    -S <serverId>      - The ServerId for this server, this may be required when
                          server.depot.root configurable is found.

    -t <filename>      - Filename for the input translation map.
                         The paths in your checkpoint are remapped through
                         the mappings in this file to resolve conflicts
                         due to inconsistent use of case. Default: none
                         See also -c.

    -u                 - Source checkpoint is from unicode mode server.
                         This option is only needed if the checkpoint is missing a
                         Checkpoint header journal note.

    -v <level>         - Output verbosity, (0-6) higher levels provide more detail

    -V                 - Print version details and exit.

Notes and Limitations

• p4migrate supports servers up to 2025.2. Newer servers may introduce schema changes; contact support before proceeding.
• Generated conflict maps (cmap) list items with multiple case variants; initial LHS == RHS. You must edit RHS case-only.
• Policies (-p lower|upper|head): applied before translation maps.
  • Locale sensitivity: upper/lower are locale-dependent. Use -L to select an appropriate locale; ‘C’ is fastest but does not fold multi-byte characters.
  • Head policy may still leave conflicts that require map edits.
  • Advanced: If you mix a policy file (-P) with a translation map (-t), the translation map is applied after the policy. Misuse can cause unexpected results; confirm intent before proceeding.
• Translation maps are case-insensitive on all platforms; parent-before-child ordering improves clarity and consistency.
• Archive renaming (-R) is available only on case-sensitive platforms and requires -r <P4ROOT>.
• Standardizing a checkpoint (-s with -o) rewrites records to a normalized format to aid diff/verification.

Migrating from Windows/macOS to Unix/Linux

Windows and macOS are generally case-insensitive; Unix/Linux are case-sensitive. Case variants that refer to the same logical item on Windows/macOS become distinct on Unix/Linux. The recommended flow:

1. Create checkpoint on source.
2. Run first pass to generate cmap; edit RHS case-only.
3. Run second pass to produce checkpoint.edited and cmap2; resolve any appended conflicts and rerun if needed.
4. Run archive renaming with -R (provide -r and -S if required).
5. Correct line endings for text files as needed (see below) and validate server operations.

Migrating from Unix/Linux to Windows/macOS

Prefer switching the target server to case-insensitive mode using p4d -C1. p4migrate is typically not required to fix case since case-insensitive servers treat variants equivalently. Still ensure archive paths are consistent, and consider using the two-pass workflow to standardize casing prior to the transition.

Line Endings Correction

When moving across platforms, line endings in archive files may need adjustment for text content. Recommended:

• Line ending conversion: More details here: Cross-Platform Helix Core Server Migration
• Use Perforce filetypes and client settings to manage text vs binary appropriately.
• Avoid altering binary content; apply EOL normalization only to text files.
• Verify with p4 print and client syncs; confirm expected line endings on target clients.

Using Locales

p4migrate has 3 locale based configurations, configured by the -L locale setting

1. If the locale is set to either 'C' or 'POSIX', p4migrate will use high performance case folding intended for 7bit characters.
2. If the locale is set to a value which contains the substring 'UTF-8', then a generic utf8 case folding algorithm will be used.
3. Otherwise, assuming that the locale specified is installed on your machine, case folding will use the (slow) locale specific case folding code available in the libc libraries

If the checkpoint is from a unicode mode server then utf8 specific case folding will be used.

if no -L locale option is passed, the 'C' locale will be used by default

There is a chance, that for a given locale setting, p4migrate will miss some case folding conversions. If this happens, multiple permutations of a given case insensitive path may still exist in the resulting checkpoint. You may wish to try the migration again using a different locale setting to see if it works better.

Using Policies

Policies can be used to apply a global transformation to all paths in your repository. If it's your policy that all filenames should be lower- or upper-case, then p4migrate can correct all exceptions to this policy and bring all your pathnames into line.

  p4migrate -p upper -c conflicts -o checkpoint.new checkpoint.NNNN
  p4migrate -p lower -c conflicts -o checkpoint.new checkpoint.NNNN

There's also a policy called 'head' which will not transform the paths in any way, but rather affects the path that will be chosen for inclusion in the conflict map. Instead of choosing the most frequently-used case-variant, it will select the case used by the head revision (in the case of conflicts) at the filename level and, for conflicts at the folder level, it will choose the most recently encountered variant used by the head revisions of the files underneath that folder.

  p4migrate -p head -c conflicts -o checkpoint.new checkpoint.NNNN

There are some caveats with the use of policies:

1. p4migrate will use the configured locale to change the case of paths
2. Your checkpoint may contain paths in different character sets, so they may not all share the same correct 'locale' settings
3. a checkpoint containing mixed file paths in both utf-8 and locale specific character sets may not convert correctly using any 'locale' setting

Advanced Policy Features

You can override your policy using the Translation Map (-t transmap) to specify the exceptions to the rule as the Translation Map is applied after the policy. When you do this, ensure that you provide a complete set of mappings and use the -c flag with p4migrate so that any conflicts (perhaps caused by missing mappings) are recorded in a conflicts map so that you can correct your translation map and try again. For example:

        p4migrate -p upper -c conflicts -t transmap -o checkpoint.new checkpoint.NNNN
 

Note, using this feature you will need to confirm that you have understood that this can casue unexpected results if applied incorrectly.

The "Translation Map" is in the same format of the conflict maps. Any path that is mentioned in the the Translation Map will be applied after the policy. In the above the policy is "upper". If the Translation Map contains:

         //depot/production/... //DEPOT/production/...
         //depot/production/gastar/... //DEPOT/production/gastar/...
 

The the paths starting with "//DEPOT/production/..." and "//DEPOT/production/gastar/..." will all be in lower case matching the translation map, and all other depot will be in upper case Matching the policy, upper. For example, your final depot layout would appear as:

     //DEPOT/FOO.TXT
     //DEPOT/DEV/FOO.TXT
     //DEPOT/production/LIVE/FOO.TXT
     //DEPOT/production/gastar/QA/FOO.TXT
 

Applying policies and Translation Maps at the same time can lead to unexpected results if applied incorectly. If in doubt, contact Perforce Technical Support for assistance.

Advanced mode caution: mixing policies and translation maps can be powerful but risky. Ensure your maps are case-only on RHS, parent-first, and consistent across the hierarchy.

Support

Contact P4 Support or visit Perforce Technical Support for assistance.