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