Perforce File Types

Perforce supports a set of file types that enable it to determine how files are stored by the Perforce service and whether the file can be diffed. When you add a file, Perforce attempts to determine the type of the file automatically: Perforce first determines whether the file is a regular file or a symbolic link, and then examines the first part of the file to determine whether it's text or binary. If any nontext characters are found, the file is assumed to be binary; otherwise, the file is assumed to be text. (Files in unicode environments are detected differently; see Perforce file type detection and Unicode.)

To determine the type of a file under Perforce control, issue the p4 opened or p4 files command. To change the Perforce file type, specify the -tfiletype option. For details about changing file type, refer to the descriptions of p4 add, p4 edit, and p4 reopen in the P4 Command Reference.

Perforce file types

Perforce supports the following file types.

Keyword

Description

Comments

Stored as

apple

Mac file

AppleSingle storage of Mac data fork, resource fork, file type and file creator.

For full details, please see the Mac client release notes.

full file, compressed, AppleSingle format

binary

Nontext file

Synced as binary files in the workspace. Stored compressed within the depot.

full file, compressed

resource

Mac resource fork

(Obsolete) This type is supported for backward compatibility, but the apple file type is recommended.

full file, compressed

symlink

Symbolic link

Perforce applications on UNIX, OS X, recent versions of Windows treat these files as symbolic links. On other platforms, these files appear as (small) text files.

delta

text

Text file

Synced as text in the workspace. Line-ending translations are performed automatically.

delta

unicode

Unicode file

Perforce services operating in unicode mode support the unicode file type. These files are translated into the local character set specified by P4CHARSET.

Perforce services not in unicode mode do not support the unicode file type.

For details, see the Internationalization Notes.

delta, UTF-8

utf16

Unicode file

Whether the service is in unicode mode or not, files are transferred as UTF-8, and translated to UTF-16 (with byte order mark, in the byte order appropriate for the user's machine) in the client workspace.

For details, see the Internationalization Notes.

delta, UTF-8

File type modifiers

You can apply file type modifiers to the base types of specific files to preserve timestamps, expand RCS keywords, specify how files are stored in the service, and more. For details about applying modifiers to file types, see Specifying how files are stored in Perforce.

The following table lists the file type modifiers.

Modifier

Description

Comments

+C

Perforce stores the full compressed version of each file revision

Default storage mechanism for binary files and newly-added text, unicode, or utf16 files larger than 10MB.

+D

Perforce stores deltas in RCS format

Default storage mechanism for text files.

+F

Perforce stores full file per revision

For large ASCII files that aren't treated as text, such as PostScript files, where storing the deltas is not useful or efficient.

+k

RCS (Revision Control System) keyword expansion

Supported keywords are as follows:

  • $Id$

  • $Header$

  • $Date$ Date of submission

  • $DateUTC$ Date of submission in UTC time zone

  • $DateTime$ Date and time of submission

  • $DateTimeUTC$ Date and time of submission in UTC time zone.

  • $DateTimeTZ$ Date and time of submission in the server's time zone, but including the actual time zone in the result.

  • $Change$

  • $File$

  • $Revision$

  • $Author$

RCS keywords are case-sensitive. A colon after the keyword (for example, $Id:$) is optional.

+ko

Limited keyword expansion

Expands only the $Id$ and $Header$ keywords. Primarily for backwards compatibility with versions of Perforce prior to 2000.1, and corresponds to the +k (ktext) modifier in earlier versions of Perforce.

+l

Exclusive open (locking)

If set, only one user at a time can open a file for editing.

Useful for binary file types (such as graphics) where merging of changes from multiple authors is not possible.

+m

Preserve original modification time

The file's timestamp on the local file system is preserved upon submission and restored upon sync. Useful for third-party DLLs in Windows environments, because the operating system relies on the file's timestamp. By default, the modification time is set to the time you synced the file.

+S

Only the head revision is stored

Older revisions are purged from the depot upon submission of new revisions. Useful for executable or .obj files.

+Sn

Only the most recent n revisions are stored, where n is a number from 1 to 10, or 16, 32, 64, 128, 256, or 512.

Older revisions are purged from the depot upon submission of more than n new revisions, or if you change an existing +Sn file's n to a number less than its current value. For details, see the P4 Command Reference.

+w

File is always writable on client

Not recommended, because Perforce manages the read-write settings on files under its control.

+x

Execute bit set on client

Used for executable files.

+X

Archive trigger required

The Perforce service runs an archive trigger to access the file. See the Perforce Server Administrator's Guide: Fundamentals for details.

Specifying how files are stored in Perforce

File revisions of binary files are normally stored in full within the depot, but only changes made to text files since the previous revision are normally stored. This approach is called delta storage, and Perforce uses RCS format to store its deltas. The file's type determines whether full file or delta storage is used.

Some file types are compressed to gzip format when stored in the depot. The compression occurs when you submit the file, and decompression happens when you sync (copy the file from the depot to your workspace). The client workspace always contains the file as it was submitted.

Warning!

To avoid inadvertent file truncation, do not store binary files as text. If you store a binary file as text from a Windows machine and the file contains the Windows end-of-file character ^Z, only the part of the file up to the ^Z is stored in the depot.

Assigning File Types for Unicode Files

The Perforce service can be run in Unicode mode to activate support for filenames and Perforce metadata that contain Unicode characters, or in non-Unicode mode, where filenames and metadata must be ASCII, but textual files containing unicode content are still supported.

If you need to manage textual files that contain Unicode characters, but do not need Unicode characters in Perforce metadata, you do not need to run Perforce in Unicode mode. Assign the Perforce utf16 file type to textual files that contain Unicode characters.

Your system administrator will be able to tell you which mode the service is using.

In either mode, Perforce supports a set of file types that enable it to determine how a file is stored and whether the file can be diffed. The following sections describe the considerations for managing textual files in Unicode environments.

To assign file type when adding a file to the depot, specify the -t option. For example:

p4 add -t utf16 newfile.txt

To change the file type of files in the depot, open the file for edit, specifying the -t option. For example:

p4 edit -t utf16 myfile.txt

Choosing the file type

When assigning file types to textual files that contain Unicode, consider the following:

  • Do you need to edit and diff the files?

    Many IDEs create configuration files that you never edit manually or diff. To ensure they are never translated, assign such files the binary file type.

  • Is your site managing files that use different character sets?

    If so, consider storing them using a utf16 file type, to ensure they are not translated but still can be diffed.

Unicode mode services translate the contents of unicode files into the character set specified by P4CHARSET. The following table provides more details about how Unicode-mode services manage the various types of text files.

Text file type

Stored by Perforce as (unicode mode)

Validated?

Translated per P4CHARSET?

Translated per client platform

text

Extended ASCII

No

No

No

unicode

UTF-8

Yes (as UTF-16 and P4CHARSET)

Yes

No

utf16

UTF-8

Yes (as UTF-16)

No

No

Non-unicode-mode services do not translate or verify the contents of unicode files. Instead, the UTF-8 data is converted to UTF-16 using the byte order appropriate to the client platform. To ensure that such files are not corrupted when you edit them, save them as UTF-8 or UTF-16 from within your editing software.

Text file type

Stored by Perforce as (unicode mode)

Validated?

Translated per P4CHARSET?

Translated per client platform

text

Extended ASCII

No

No

No

unicode

UTF-8

Yes (as UTF-16 and P4CHARSET)

No

No

utf16

UTF-8

Yes (as UTF-16)

No

Yes

Perforce file type detection and Unicode

In both Unicode mode and non-Unicode mode, if you do not assign a file type when you add a file to the depot, Perforce (by default) attempts to detect file type by scanning the first 65536 characters of the file. If nonprintable characters are detected, the file is assigned the binary file type. (In Unicode mode, a further check is performed: if there are no nonprintable characters, and there are high-ASCII characters that are translatable using the character set specified by P4CHARSET, the file is assigned the unicode file type.)

Finally (for services running in Unicode mode or non-Unicode mode), if a UTF-16 BOM is present, the file is assigned the utf16 file type. Otherwise, the file is assigned the text file type. (In Unicode mode, a further check is performed: files with high-ASCII characters that are undefined in the character set specified by P4CHARSET are assigned the binary file type.)

In most cases, there is no need to override Perforce's default file type detection. If you must override Perforce's default file type detection, you can assign Perforce file types according to a file's extension, by issuing the p4 typemap command. For more about using the typemap feature, refer to the Perforce Server Administrator's Guide: Fundamentals, and the P4 Command Reference.

Overriding file types

Some file formats (for example, Adobe PDF files, and Rich Text Format files) are actually binary files, but they can be mistakenly detected by Perforce as being text. To prevent this problem, your system administrator can use the p4 typemap command to specify how such file types are stored. You can always override the file type specified in the typemap table by specifying the -t filetype option.

Preserving timestamps

Normally, Perforce updates the timestamp when a file is synced. The modification time (+m) modifier is intended for developers who need to preserve a file's original timestamp. This modifier enables you to ensure that the timestamp of a file synced to your client workspace is the time on your machine when the file was submitted.

Windows uses timestamps on third-party DLLs for versioning information (both within the development environment and also by the operating system), and the +m modifier enables you to preserve the original timestamps to prevent spurious version mismatches. The +m modifier overrides the client workspace [no]modtime setting (for the files to which it is applied). For details about this setting, refer to File type modifiers.

Expanding RCS keywords

RCS (Revision Control System), an early version control system, defined keywords that you can embed in your source files. These keywords are updated whenever a file is committed to the repository. Perforce supports some RCS keywords.

To activate RCS keyword expansion for a file, use the +k modifier. RCS keywords are expanded as follows.

Keyword

Expands To

Example

$Author$

Perforce user submitting the file

$Author: bruno $

$Change$

Perforce changelist number under which file was submitted

$Change: 439 $

$Date$

Date of last submission in format YYYY/MM/DD

$Date: 2011/08/18 $

$DateTime$

Date and time of last submission in format YYYY/MM/DDhh:mm:ss

Date and time are as of the local time on the Perforce service at time of submission.

$DateTime: 2011/08/18 23:17:02 $

$File$

Filename only, in depot syntax (without revision number)

$File: //depot/path/file.txt $

$Header$

Synonymous with $Id$

$Header: //depot/path/file.txt#3 $

$Id$

Filename and revision number in depot syntax

$Id: //depot/path/file.txt#3 $

$Revision$

Perforce revision number

$Revision: #3 $

To display a file without expanding its keywords, use p4 print -k filename.