File Types
Synopsis
Perforce supports six base file types:
text
files,- compressed
binary
files, - native
apple
files on Mac, - Mac
resource
forks, - symbolic links (
symlink
s), and unicode
andutf16
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 file |
Synced as text in the workspace. Line-ending translations are performed automatically. |
deltas in RCS format |
|
Non-text file |
Synced as binary files in the workspace. Stored compressed within the depot. |
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. On Windows you require |
deltas in RCS format |
|
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. |
|
Mac resource fork |
The only file type for Mac resource forks in Perforce 99.1 and before.
Still supported, but the For full details, see the Mac client release notes. |
full file, compressed |
|
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. |
RCS deltas in UTF-8 format |
|
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). |
|
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 |
---|---|---|
|
File is always writable on client |
|
|
Execute bit set on client |
Used for executable files. |
|
Old-style keyword expansion |
Expands only the This pair of modifiers exists primarily for backwards compatibility with
versions of Perforce prior to 2000.1, and corresponds to the |
|
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,
UTC keywords are better suited to describe events in globally distributed installations. Supported keywords are as follows:
|
|
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. |
|
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, uncompressed |
Useful for large binaries, or for long ASCII files that are not read by users as text, such as PostScript files. |
|
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
|
|
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. |
|
Archive trigger required |
The Perforce service runs an |
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 foredit
as the specified type. The file’s type is changed to the specifiedfiletype
only after it is submitted to the depot.- p4 reopen -t
filetype
filespec
changes the type of a file already open foradd
oredit
.
The filetype
argument is specified as
[
. For example, to
change basetype
]
+modifiers
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 |
---|---|---|
|
|
Active Server Page file |
|
|
Video for Windows file |
|
|
Windows bitmap file |
|
|
Btrieve database file |
|
|
Conference link file |
|
|
Cascading style sheet file |
|
|
Microsoft Word document |
|
|
Microsoft Word template |
|
|
Export file (Microsoft Visual C++) |
|
|
GIF graphic file |
|
|
Gzip compressed file |
|
|
HTML file |
|
|
HTML file |
|
|
Icon file |
|
|
Active Server Include file |
|
|
Initial application settings file |
|
|
JPEG graphic file |
|
|
JavaScript language source code file |
|
|
Library file (several programming languages) |
|
|
Log file |
|
|
MPEG video file |
|
|
Adobe PDF file |
|
|
Sybase Power Designer file |
|
|
Microsoft PowerPoint file |
|
|
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 |
---|---|---|
|
File name and revision number in depot syntax. |
|
|
Synonymous with |
|
|
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. |
|
|
Perforce changelist number under which file was submitted. |
|
|
File name only, in depot syntax (without revision number). |
|
|
Perforce revision number. |
|
|
Perforce user submitting the file. |
|
Usage Notes
- The type of an existing file can be determined with
p4 opened
orp4 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 withbinary
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
+S
(temporary object) modifier tells Perforce to store only the most recentn
n
revisions of the file in the depot. If you change an existing file into a temporary object, subsequent revisions (after then
th) will purge the revisions stored after the old head revision, but revisions to the file stored in the depot before the+S
modifier was used will remain unaffected. (Syncing to a non-head revision submitted after then
+S
modifier was used will delete the file from your workspace. Such revisions are displayed asn
purge
operations in the output ofp4 filelog
.) - Running
p4 integrate
on temporary object files (+S
and+S
) does not produce a lazy copy; the integratedn
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 ap4 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 themodtime
("file’s timestamp at time of submission") ornomodtime
("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