Perforce Public Knowledge Base - Changing Case Handling Behavior on Linux
Downloads Blog Company Integrations Careers Contact Try Free
Menu Search
Reset Search



Changing Case Handling Behavior on Linux

« Go Back




This article describes the steps needed to change the native case handling behavior of a Perforce Server on Linux (case sensitive) to the non-native case insensitive behavior of Windows.

Converting an existing Perforce Server on Linux from a case sensitive to a case insensitive might require data loss and is not supported; please inquire with Perforce Consulting if you are interested in converting the case handling behavior of your Perforce Server on Linux.

Note that moving from Windows to Linux and retaining case handling is supported. For information on that platform migration process.

Running the Perforce Server in non-standard case-handling mode requires using the-C1 flag. The -C1 flag was first supported in the 2010.1 version of the Perforce Server.

You must always use the -C1 flag when invoking p4d operations. For example, use of this flag is necessary when starting your Perforce Server and when running checkpoint recovery operations.

WARNING: Use of the -C1 flag prior to 2010.1 is not supported. Prior to 2007.2, if you failed to always use the -C1 flag when invoking p4d operations, you would corrupt your Perforce database. Beginning with the 2007.2 version of p4d, inconsistent use of the (previously undocumented) -C1 flag generates a server error, rather than database corruption.

To change the case handling behavior of your Perforce Server on Linux, you need to first find and resolve any conflicts with files and directory names that vary in case only.

To determine if you have case variant file names, you must use the p4migrate tool. The p4migrate tool will examine your Perforce database files and identify any case conflicts.

Documentation for p4migrate can be found here:


Once case variants have been identified by p4migrate, you must decide how to treat them. The options are:


  1. Obliterate the case variant paths (recommended)
  2. Perform a "deep rename" of one (or more) of the case variant paths and rename the associated archive files


Because moving to case insensitive behavior entails collapsing the file namespace, again, you must decide how to resolve these conflicts and that requires either renaming some file paths, or removing (obliterating) versioned file content.

Because the renaming process requires database record editing and is error prone, the safest method to resolving case conflicts is to obliterate the conflicting file path(s).

The metadata and archive "deep rename" process is error prone, requires understanding of the Perforce database schema, and is only recommended to be undertaken by Perforce Consulting.

Note: When running in -C1 mode on a case-sensitive sensitive file system, the Perforce Server can read mixed case metadata, but only reads and writes lowercase archive files. Therefore, all of the archive files located under P4ROOT must be converted to lowercase. Otherwise, Perforce operations that access files (for example, p4 sync and p4 verify)

The p4migrate tool also provides a method for renaming database file paths to a consistent case, however, this functionality is normally reserved from moving from a case insensitive file system (where case differences do not matter) to a case sensitive file system, where such differences do matter. Attempting to unify the case of files on a case sensitive file system (with real content differences between case variants) will lead to a loss of data. This potential case folding condition is similar to the unsupported migration of a Perforce Server from Linux to Windows.

Example Case Handling Conversion

Below is the case handling conversion process in a step by step format.


p4d -r $P4ROOT -jc myCheckpoint
Checkpointing to myCheckpoint.ckp.66...
Saving journal to myCheckpoint.jnl.65...
Truncating journal...
p4d -r $P4ROOT -C1 -jr myCheckpoint.ckp.66
Perforce db files in '$P4ROOT' will be created if missing...
Recovering from myCheckpoint.ckp.66...
p4d -C1 -r $P4ROOT -p 1666 &
  1. Stop the Perforce Server on your Linux machine;
  2. Take a checkpoint:
  3. Run p4migrate to identify any case conflicts:
    p4migrate -c collision myCheckpoint.ckp.66
  4. If p4migrate does not detect any case conflicts, then skip to Step #6
  5. If p4migrate detects case conflicts, then you need to make the decision on how to rename the case variant files. By default, p4migrate will produce a case conflict map which provides a suggested mapping for normalizing (renaming files) to use the same case. However, for this conversion process, you must rename files to use completely different names. For example

    * NEED EXAMPLE Metadata rename PROCESS HERE
    * Use p4migrate or sed? Lowercase lbrFile?

  6. Rebuild your database from the checkpoint, being sure to include the -C1 flag:
  7. Once the metadata is case consistent and case variant names have been resolved (by rename or obliterate in Step #5), then you must make sure that your archive files (the version file content under $P4ROOT/depot) is renamed to the appropriate case.

    * NEED EXAMPLE Archive rename PROCESS HERE
    * Use p4migrate? Lowercase everything

  8. Start the Perforce Server, making sure you include the -C1 flag:
At this point, you can run p4 verify -q //... to verify the integrity of the archive files.


Always Use -C1

As noted in the warning above, once you use the -C1 flag, you must always use it thereafter. This means that you must update your scripts to hardcode use of whenever you invoke p4d, or use a suitable alternative.

As an alternative to hardcoding -C1 in your scripts, you can maintain consistent use of this flag by creating a wrapper for the Perforce Server, p4d. For example, you can create a script similar to the one detailed below, specifying the path to your p4d executable, such that calls to p4d always invoke 'p4d -C1':

exec $P4D -C1 "$@"
Name this script "p4d" and include it in the search path. Ensure that the real p4d executable is NOT included in the search path. These two steps ensure that each time you run p4d, this script is launched rather than the actual executable. The -C1 flag is included automatically, and all additional parameters are passed to the p4d executable.

If you attempt invoke p4d commands against a database with different case-handling characteristics (using version 2007.2 or greater), you will receive the following error:
Perforce server error:
    Database open error on db.counters!
    BTree Case Order Mismatch!


Related Links



Was this article helpful?



Please tell us how we can make this article more useful.

Characters Remaining: 255