CR/LF Issues and Text Line-endings
How does Perforce handle CR/LF issues?
How does Perforce translate text file line-endings?
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 0000000015 D:P4WORKtest>od -c line_end.mac 0000000000 M a c l i n e e n d \r 0000000015 D:P4WORKtest>od -c line_end.unix 0000000000 U n i x l i n e e n d \n 0000000016
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
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
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
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
mac line-end option and then syncing files into their
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
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
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,
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
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
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)
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.