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
-t
option. For
details about changing file type, refer to the descriptions of p4
add, p4 edit, and p4 reopen
in the
P4
Command Reference.
filetype
Perforce file types
Perforce supports the following file types.
Keyword |
Description |
Comments |
Stored as |
---|---|---|---|
|
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 |
|
Nontext file |
Synced as binary files in the workspace. Stored compressed within the depot. |
full file, compressed |
|
Mac resource fork |
(Obsolete) This type is supported for backward compatibility,
but the |
full file, compressed |
|
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 file |
Synced as text in the workspace. Line-ending translations are performed automatically. |
delta |
|
Unicode file |
Perforce services operating in unicode mode support the
Perforce services not in unicode mode do not support the
For details, see the Internationalization Notes. |
delta, UTF-8 |
|
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 |
---|---|---|
|
Perforce stores the full compressed version of each file revision |
Default storage mechanism for |
|
Perforce stores deltas in RCS format |
Default storage mechanism for |
|
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. |
|
RCS (Revision Control System) keyword expansion |
Supported keywords are as follows:
RCS keywords are case-sensitive. A colon after the keyword (for
example, |
|
Limited keyword expansion |
Expands only the |
|
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. |
|
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. |
|
Only the head revision is stored |
Older revisions are purged from the depot upon submission of new
revisions. Useful for executable or |
|
Only the most recent |
Older revisions are purged from the depot upon submission of
more than |
|
File is always writable on client |
Not recommended, because Perforce manages the read-write settings on files under its control. |
|
Execute bit set on client |
Used for executable files. |
|
Archive trigger required |
The Perforce service runs an |
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 |
Translated per client platform |
---|---|---|---|---|
|
Extended ASCII |
No |
No |
No |
|
UTF-8 |
Yes (as UTF-16 and |
Yes |
No |
|
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 |
Translated per client platform |
---|---|---|---|---|
|
Extended ASCII |
No |
No |
No |
|
UTF-8 |
Yes (as UTF-16 and |
No |
No |
|
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
option.
filetype
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 |
---|---|---|
|
Perforce user submitting the file |
|
|
Perforce changelist number under which file was submitted |
|
|
Date of last submission in format
|
|
|
Date and time of last submission in format
Date and time are as of the local time on the Perforce service at time of submission. |
|
|
Filename only, in depot syntax (without revision number) |
|
|
Synonymous with |
|
|
Filename and revision number in depot syntax |
|
|
Perforce revision number |
|
To display a file without expanding its keywords, use p4 print -k
filename
.