Perforce 2008.1 P4 User's Guide


<< Previous Chapter Glossary	Table of Contents Index Perforce on the Web	Next Chapter >> Index

Appendix B
Perforce File Types

Perforce supports a set of file types that enable it to determine how files are stored by the Perforce server 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" on page 118.)

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 -t filetype flag. For details about changing file type, refer to the descriptions of p4 add, p4 edit, and p4 reopen in the Perforce Command Reference.

Perforce file types

Perforce supports the following file types.


Keyword	Description	Comments	How stored by the Perforce server
`apple`	Macintosh file	AppleSingle storage of Macintosh 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`	Macintosh resource fork	(Obsolete) This type is supported for backward compatibility, but the `apple` file type is recommended.	full file, compressed
`symlink`	Symbolic link	UNIX and BeOS client machines treat these files as symbolic links. Non-UNIX client machines treat them as text files.	delta
`text`	Text file	Synced as text in the workspace. Line-ending translations are performed automatically.	delta
`unicode`	Unicode file	Perforce servers operating in unicode mode support the `unicode` file type. These files are translated into the local character set specified by `P4CHARSET`. Perforce servers not in unicode mode do not support the `unicode` file type. For details, see the Internationalization Notes.	UTF-8
`utf16`	Unicode file	If the Perforce server is operating in unicode mode, files are translated into the local character set as specified by `P4CHARSET`. If the Perforce server is operating in non-unicode mode, files are transferred as UTF-8, and translated to UTF-16 (with byte order mark, in the byte order appropriate for the client machine) in the client workspace. For details, see the Internationalization Notes.	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 on the server, and more. For details about applying modifiers to file types, see"Specifying how files are stored in the server" on page 116.

The following table lists the file type modifiers.


Modifier	Description	Comments
`+C`	Server stores the full compressed version of each file revision	Default server storage mechanism for `binary` files.
`+D`	Server stores deltas in RCS format	Default server storage mechanism for `text` files.
`+F`	Server 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: $Author$ $Change$ $Date$ $DateTime$ $File$ $Header$ $Id$ $Revision$ 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 on the server	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 on the server, 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.
`+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.

Specifying how files are stored in the server

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 server to the 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 client 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 server 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 your server 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 server is using.

In either mode, Perforce supports a set of file types that enable it to determine how a file is stored by the Perforce server 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 flag. 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 flag. 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 servers translate the contents of unicode files into the character set specified by P4CHARSET. The following table provides more details about how Unicode-mode servers manage the various types of text files.


Text file type	Stored by server 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 servers 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 server 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 attempts to detect file type by scanning the first 8192 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 servers 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 System Administrator's Guide, and the Perforce 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 flag.

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 the client 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" on page 114.

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: 2000/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 server at time of submission.	$DateTime: 2000/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 $