File Types

Synopsis

Perforce supports six base file types:

text files,
compressed binary files,
native apple files on Mac,
Mac resource forks,
symbolic links (symlinks), and
unicode and utf16 files.

File type modifiers are then applied to the base types allowing for support of RCS keyword expansion, file compression, and more.

When adding files, Perforce first examines the typemap table to see if the system administrator has defined a file type for the file(s) being added. If a match is found, the file’s type is set as defined in the typemap table. If a match is not found, Perforce examines the first bytes of the file based on the filesys.binaryscan configurable (by default, 65536 bytes) to determine whether it is text or binary, and the files are stored in the depot accordingly.

By default, text file revisions are stored in reverse delta format; newly-added text files larger than the limit imposed by the filetype.maxtextsize configurable (by default, 10 MB) are assigned filetype text+C and stored in full. Files compressed in the .zip format (including .jar files) are also automatically detected and assigned the type ubinary. Other binary revisions are stored in full, with compression.

(Files in unicode environments are detected differently; for details, see the Internationalization Notes.)

Perforce administrators can use the type mapping feature (p4 typemap) to override Perforce’s default file type detection mechanism. This feature is useful for binary file formats (such as Adobe PDF, or Rich Text Format) where files can start with large portions of ASCII text, and might otherwise be mistaken for text files.

Perforce administrators can use the filesys.binaryscan and filetype.maxtextsize configurables (see p4 configure) to change the default limits of 65536 bytes for text/binary detection, and the 10 MB RCS text file size limit respectively.

Base filetypes

The base Perforce file types are:

Keyword	Description	Comments	Stored as
`text`	Text file	Synced as text in the workspace. Line-ending translations are performed automatically.	deltas in RCS format
`binary`	Non-text file	Synced as binary files in the workspace. Stored compressed within the depot.	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. On Windows you require `admin` privileges or an appropriate group policy must be set; otherwise, you get text files.	deltas in RCS format
`apple`	Multi-forked Mac file	AppleSingle storage of Mac data fork, resource fork, file type and file creator. For full details, see the Mac client release notes.	full file, compressed, AppleSingle format.
`resource`	Mac resource fork	The only file type for Mac resource forks in Perforce 99.1 and before. Still supported, but the `apple` file type is preferred. For full details, see the Mac client release notes.	full file, compressed
`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.	RCS deltas in UTF-8 format
`utf8`	Unicode file	Whether the service is in unicode mode or not, files are transferred as UTF-8 in the client workspace. For details, see the Internationalization Notes.	RCS deltas in UTF-8 format without BOM (byte order mark).
`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.	RCS deltas in UTF-8 format

File type modifiers

The file type modifiers are:

Modifier	Description	Comments
`+w`	File is always writable on client
`+x`	Execute bit set on client	Used for executable files.
`+ko`	Old-style keyword expansion	Expands only the $Id$ and $Header$ keywords: This pair of modifiers exists primarily for backwards compatibility with versions of Perforce prior to 2000.1, and corresponds to the `+k` (`ktext`) modifier in earlier versions of Perforce.
`+k`	RCS keyword expansion	Expands RCS (Revision Control System) keywords. RCS keywords are case-sensitive. When using keywords in files, a colon after the keyword (for instance, $Id:$ ) is optional. UTC keywords are better suited to describe events in globally distributed installations. 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$
`+l`	Exclusive open (locking)	If set, only one user at a time will be able to open a file for editing. Useful for binary file types (such as graphics) where merging of changes from multiple authors is meaningless.
`+C`	Perforce stores the full compressed version of each file revision	Default storage mechanism for `binary` files and newly-added `text`, `unicode`, and `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, uncompressed	Useful for large binaries, or for long ASCII files that are not read by users as text, such as PostScript files.
`+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. Earlier revisions unaffected; see Usage Notes for details.
`+m`	Preserve original modtime	The file’s timestamp on the local filesystem is preserved upon submission and restored upon sync. Useful for third-party DLLs in Windows environments.
`+X`	Archive trigger required	The Perforce service runs an `archive` trigger to access the file. See the Helix Versioning Engine Administrator Guide: Fundamentals for details.

A file’s type is normally preserved between revisions, but can be overridden or changed with the -t option during add, edit, or reopen operations:

p4 add -t filetype filespec adds the files as the specified type.
p4 edit -t filetype filespec opens the file for edit as the specified type. The file’s type is changed to the specified filetype only after it is submitted to the depot.
p4 reopen -t filetype filespec changes the type of a file already open for add or edit.

The filetype argument is specified as [basetype] +modifiers. For example, to change script.sh’s type to executable text with RCS keyword expansion, use p4 edit -t text+kx script.sh.

Partial filetypes are also acceptable. For example, to change an existing text file to text+x, use p4 reopen -t +x script.sh. Most partial filetype modifiers are added to the filetype, but the storage modifiers (+C, +D, and +F) replace the file’s storage method. To remove a modifier, you must specify the full filetype.

Perforce file types for common file extensions

The following table lists recommended Perforce file types and modifiers for common file extensions.

File Type	Perforce file type	Description
`.asp`	`text`	Active Server Page file
`.avi`	`binary+F`	Video for Windows file
`.bmp`	`binary`	Windows bitmap file
`.btr`	`binary`	Btrieve database file
`.cnf`	`text`	Conference link file
`.css`	`text`	Cascading style sheet file
`.doc`	`binary`	Microsoft Word document
`.dot`	`binary`	Microsoft Word template
`.exp`	`binary+w`	Export file (Microsoft Visual C++)
`.gif`	`binary+F`	GIF graphic file
`.gz`	`binary+F`	Gzip compressed file
`.htm`	`text`	HTML file
`.html`	`text`	HTML file
`.ico`	`binary`	Icon file
`.inc`	`text`	Active Server Include file
`.ini`	`text+w`	Initial application settings file
`.jpg`	`binary`	JPEG graphic file
`.js`	`text`	JavaScript language source code file
`.lib`	`binary+w`	Library file (several programming languages)
`.log`	`text+w`	Log file
`.mpg`	`binary+F`	MPEG video file
`.pdf`	`binary`	Adobe PDF file
`.pdm`	`text+w`	Sybase Power Designer file
`.ppt`	`binary`	Microsoft PowerPoint file
`.xls`	`binary`	Microsoft Excel file

For more about mapping file names to Perforce filetypes, see the p4 typemap command.

Keyword Expansion

RCS keywords are expanded as follows:

Keyword	Expands To	Example
$Id$	File name and revision number in depot syntax.	$Id: //depot/path/file.txt#3 $
$Header$	Synonymous with $Id$ .	$Header: //depot/path/file.txt#3 $
$Date$	Date of last submission in format `YYYY/MM/DD`	$Date: 2010/08/18 $
$DateTime$	Date and time of last submission in format `YYYY/MM/DD hh:mm:ss` Date and time are as of the local time on the Perforce service at time of submission.	$DateTime: 2010/08/18 23:17:02 $
$Change$	Perforce changelist number under which file was submitted.	$Change: 439 $
$File$	File name only, in depot syntax (without revision number).	$File: //depot/path/file.txt $
$Revision$	Perforce revision number.	$Revision: #3 $
$Author$	Perforce user submitting the file.	$Author: edk $

Usage Notes

The type of an existing file can be determined with p4 opened or p4 files.
Delta storage (the default mode with text files) is a method whereby only the differences (or deltas) between revisions of files are stored. Full file storage (the default mode with binary files) involves the storage of the entire file. The file’s type determines whether full file or delta storage is used. Perforce uses RCS format for delta storage.
Some of the file types are compressed to gzip format for storage in the depot. The compression occurs during the submission process, and decompression happens while syncing. The process is transparent to the user; the client workspace always contains the file as it was submitted.
Symbolic links in non-UNIX client workspaces appear as small text files containing a relative path to the linked file. Editing these files on a non-UNIX client should be done with caution, as submitting them to the depot may result in a symbolic link pointing to a nonexistent file on the UNIX workspace.
Changing a file’s type does not affect earlier revisions stored in the depot.

For instance, changing a file’s type by adding the +Sn (temporary object) modifier tells Perforce to store only the most recent n revisions of the file in the depot. If you change an existing file into a temporary object, subsequent revisions (after the nth) will purge the revisions stored after the old head revision, but revisions to the file stored in the depot before the +Sn modifier was used will remain unaffected. (Syncing to a non-head revision submitted after the +Sn modifier was used will delete the file from your workspace. Such revisions are displayed as purge operations in the output of p4 filelog.)
Running p4 integrate on temporary object files (+S and +Sn) does not produce a lazy copy; the integrated tempobj file consumes additional diskspace on the shared versioning service.
The modtime (+m) modifier is a special case: It is intended for use by developers who need to preserve a file’s original timestamp.

If a client workspace uses the modtime option, the file date is not guaranteed to advance for each revision. For example, if a file is copy integrated ("accept theirs"), its timestamp will reflect that of the source file. If a user checks in a file with an old date, the client workspace file will reflect that same, old date. Normally, Perforce updates the timestamp when a file is synced; the modtime option enables a user to ensure that the timestamp of a file in a client workspace after a p4 sync will be the original timestamp existing on the file at the time of submission (that is, not the time at the Perforce versioning service at time of submission, and not the time on the user’s workstation at the time of sync).

The most common case where this is useful is development involving the third-party DLLs often encountered in Windows environments. Because the timestamps on such files are often used as proxies for versioning information (both within the development environment and also by the operating system), it is sometimes necessary to preserve the files' original timestamps regardless of a Perforce user’s client settings.

The +m modifier on a file allows this to happen; if set, Perforce will ignore the modtime ("file’s timestamp at time of submission") or nomodtime ("date and time on the client at time of sync") option setting of the client workspace when syncing the file, and always restore the file’s original timestamp at the time of submit.

Versions of Perforce prior to 99.1 used a set of keywords to specify file types. The following table lists the older keywords and their current base file types and modifiers:

Old Keyword	Description	Base Filetype	Modifiers
`text`	Text file	`text`	none
`xtext`	Executable text file	`text`	`+x`
`ktext`	Text file with RCS keyword expansion	`text`	`+k`
`kxtext`	Executable text file with RCS keyword expansion	`text`	`+kx`
`binary`	Non-text file	`binary`	none
`xbinary`	Executable binary file	`binary`	`+x`
`ctext`	Compressed text file	`text`	`+C`
`cxtext`	Compressed executable text file	`text`	`+Cx`
`symlink`	Symbolic link	`symlink`	none
`resource`	Mac resource fork	`resource`	none
`uresource`	Uncompressed Mac resource fork	`resource`	`+F`
`ltext`	Long text file	`text`	`+F`
`xltext`	Executable long text file	`text`	`+Fx`
`ubinary`	Uncompressed binary file	`binary`	`+F`
`uxbinary`	Uncompressed executable binary file	`binary`	`+Fx`
`tempobj`	Temporary object	`binary`	`+FSw`
`ctempobj`	Temporary object (compressed)	`binary`	`+Sw`
`xtempobj`	Temporary executable object	`binary`	`+FSwx`
`xunicode`	Executable unicode	`unicode`	`+x`
`xutf16`	Executable UTF-16	`utf16`	`+x`

P4 Command Reference (2016.1)