When editing text files in cross-platform environments, you must account for different line termination conventions. Perforce can be configured to automatically translate line-endings from one operating system's convention to another, or configured to ignore line-ending translation. These configurations apply only to text files.
The following are the various line termination conventions:
- On UNIX, text file line-endings are terminated with a newline character (ASCII 0x0a, represented by the \
n escape sequence in most languages), also referred to as a linefeed (LF).
- On Windows, line-endings are terminated with a combination of a carriage return (ASCII 0x0d or \
r) and a newline(\
n), also referred to as CR/LF.
- On the Mac Classic (Mac systems using any system prior to Mac OS X), line-endings are terminated with a single carriage return (\r or CR). (Mac OS X uses the UNIX convention.)
The following example files demonstrate the various line-end conventions. They are displayed using the UNIX tool od (octal dump) on a Windows machine:
D:P4WORKtest>od -c line_end.pc
0000000000 P C l i n e e n d \r \n
D:P4WORKtest>od -c line_end.mac
0000000000 M a c l i n e e n d \r
D:P4WORKtest>od -c line_end.unix
0000000000 U n i x l i n e e n d \n
Current Versions of Perforce
On the server side, Perforce processes all text files using Unix-style LF line-endings. Although Perforce stores server archive files on disk in the operating system's native line termination convention (CR/LF on Windows, LF on Unix), all line-endings are normalized to Unix-style LF line-endings for internal Perforce Server operations such as p4 sync, p4 submit and p4 diff.
On the client workspace side, Perforce handling of line-endings is determined by a global option for each clientspec. When you sync text files to a client workspace with p4 sync, or submit them back to a Perforce Server with p4 submit, their line-endings are converted as specified in the clientspec LineEnd section.
Beginning with the 2001.1 version of Perforce, there are five possible workspace options for handling text file line-endings. These options for line-end treatment are:
local The use mode native to the client (default).
unix Linefeed: UNIX style.
mac Carriage return: Macintosh style.
win Carriage return-linefeed: Windows style.
share Hybrid: writes UNIX style but reads UNIX, Mac, or Windows style.
The default value for all Perforce client workspaces is
local, meaning that files sync to the client workspace using the client platform's standard line-ending characters. So the default LineEnd section of the clientspec would show the following:
We recommend that you start with the
local setting. To set your client workspace line ending, run P4V and select "Connection -> Edit Current Workspace" and click the Advanced tab, then choose local.
On UNIX and Mac OS X client workspaces, the default
local setting does not cause any line-end conversion. Perforce client workspaces on UNIX store text files with LF line-endings. Because the Perforce Server uses LF line-endings for operations involving text files, there is no need to do any line-end conversion in this case.
By contrast, syncing files to a Windows or Macintosh workspace requires line-end conversion, because those operating system's native line termination formats are different from UNIX. In these cases, using the
local setting converts LF to CR/LF in the Windows workspace and LF to CR in the Macintosh workspace. When files are submitted back to the Perforce Server, the line-endings are converted back to LF.
The Perforce line-end options can be used to convert your text file line endings regardless of the platform where your client workspace resides. For example, a Mac Classic user can set their client workspace line-end option to
win, to sync text files to their workspace and retain Windows-style CR/LF line-endings. UNIX users can create client workspace files with Macintosh CR line termination by choosing the
mac line-end option and then syncing files into their workspace.
unix client workspace option on a UNIX or Mac OS X client is equivalent to using the
local setting. Similarly, the
local setting for a Windows workspace is equivalent to
win, and the
local setting for a Mac Classic workspace is equivalent to
mac. Again, the
local setting is equivalent to the operating system's native line termination convention.
You might have files in your workspace that have mixed line termination conventions. For example, you might work in a cross platform environment and use a text editor that can save files with multiple line-ending formats. In this case, it is possible to edit files and inadvertently save them with spurious line-end characters. For example, saving a text file with CRLF line-endings in a
unix workspace and then submitting it results in the files being stored in the depot with extra CR characters at the end of each line. When these files are synced to other
unix workspaces, they will have CRLF line-endings rather than the correct LF line-endings, and when these files are synced to
win workspaces, they will have CRCRLF line-endings (since each LF in the original file is converted to CRLF).
share option is useful. The
share option is used to "normalize" mixed line-endings into UNIX line-end format. The
share option does not affect files that are synced into a client workspace, however, when files are submitted back to the Perforce Server, the
share option converts all Windows-style CRLF line-endings and all Mac-style CR line-endings to the UNIX-style LF, leaving lone LFs untouched.
For more information on the current LineEnd options see the p4 client section of the command reference.
Previous Versions of Perforce (99.1 to 2000.1)
Perforce clientspecs have a single client workspace option,
[no]crlf, that toggles line-ending translation on and off for all files on Windows and Macintosh clients. On UNIX clients, this setting is ignored.
The default value on both Windows and Mac Classic clients is
crlf option enables line-end translation using the operating system's default line termination convention -- CR for Mac Classic text files, CR/LF for Windows text files.
To override the default CR/LF translation behavior you set the clientspec option to
nocrlf. In this case, line-end translation is ignored when files are retrieved from, or submitted to, the Perforce Server. This setting is useful in instances where you want to preserve UNIX-style line-endings in a Windows client workspace. For example, if you were using UNIX shell tools on Windows or mounting NFS drives on a Windows based machine, preserving the UNIX-style line-endings would be preferable. In these cases, your text editor is a factor. Some Windows editors only save files with CR/LF endings, while others can save files in either PC, UNIX or Mac line-end format. As an example, if your client workspace is set to ignore line-end translation (
nocrlf), and your text editor saved files in Windows format (CR/LF), then your files will contain extra carriage returns when submitted back to the server. When such files are then synced to a UNIX client workspace, they contain spurious
^M (Control-M) characters at the end of lines. To avoid this, you must save text files in the correct line-end format when using the old
nocrlf clientspec option.
An alternative to setting the old
nocrlf option is to treat a file as type
binary. This preserves whatever line termination style the file is saved with, because line-end translation is ignored for binary files. However, this configuration also disables all other Perforce text-specific features for that file, including RCS reverse-delta storage and three-way merging capability.
Previous Versions of Perforce (98.2 and earlier)
local translation option is implicit and cannot be altered.
Note: It is possible to add text files to the Perforce repository as type binary or binary+D files in order to bypass line-ending translation for those files. If you do add text files as Perforce type binary, you will need to use the -t flag when diffing or merging in order to treat the files as text.