Wiki: DebugInfo: FileFormat

transformedtext Object
(
    [_type] => pagetype_wikitext Object
        (
        )

    [_basepage] => FileFormat
    [_content] => Array
        (
            [0] => <div class="wikitext"><h2>The 'fileformat' option</h2>
<p class="tightenable"><b>'fileformat'</b> (<b>'ff'</b> for short) controls the way that Vim handles different line-ending sequences. Vim recognizes three file formats: unix, dos, and mac.  Each of these file formats differs in the line-ending character sequences used on disk.  Unix uses a LF (line feed; ^J or 0x0A), Mac uses a CR (carriage return; ^M or 0x0D), and Dos uses CRLF (^M^J or 0x0D0A).</p>
<h3>Format conversion</h3>
<p class="tightenable">Assuming that the fileformat has been properly detected (see below), it is very simple to convert to a different format.  Simply set <b>'ff'</b> to the desired format name; for example, if you are editing a dos file and want to convert to unix, just do <b>:set ff=unix</b>.  That's it.  The next time the file is written, unix line ends will be used.  Things are a little tougher when your file has different ending sequences on different lines; this situation is discussed below.</p>
<h3>Mass conversion</h3>
<p class="tightenable top">As absolon was kind enough to point out in #vim, you can do mass conversion from the shell like so:</p>
<pre class="tightenable">
vim +&quot;argdo set ff=&lt;format&gt;&quot; +wqa &lt;files&gt;</pre>
<p class="tightenable">This will set <b>'fileformat'</b> for each file in the argument list, then quit, saving all files.</p>
<p class="tightenable bottom">See :help argdo and :help -c if you need more detail on what this does and why.</p>
<h3>'ff' Detection -- 'fileformats'</h3>
<p class="tightenable">When reading a file, Vim tries to detect the proper fileformat.  The way it does this is controlled by the <b>'fileformats'</b> (<b>'ffs'</b>) option.  <b>'ffs'</b> contains a comma separated list of the formats to try.  Each platform has its own default value for <b>'ffs'</b>:</p>
<ul><li class="tightenable bottom">unix - ffs=unix,dos</li>
<li class="tightenable top bottom">dos / windows - ffs=dos,unix</li>
<li class="tightenable top">mac - ffs=mac,unix,dos.</li>
</ul>
<p class="tightenable">Basically, Vim tries to find a line-ending sequence which appears at the end of every line, and then uses that for <b>'ff'</b>.  This process can get fooled in two ways:</p>
<ol><li class="tightenable bottom">The true fileformat is not found in <b>'fileformats'</b>, eg a Mac file on a Unix platform using the defaults</li>
<li class="tightenable top">There is a mix of line-ending sequences.  This can happen when mixing tools made for different platforms.</li>
</ol>
<h4>When Detection Goes Awry</h4>
<p class="tightenable">When <b>'ff'</b> is not detected correctly, you will usually see part or all of the line ending sequences in the editor window.  Here is a short illustration of what you see when a mismatch happens.</p>
<table class="wiki-dl-table" border="1" cellspacing="0" cellpadding="6"><tr class="tightenable"><th>File contents</th>
<td><pre class="tightenable top bottom">
Line 1
Line 2</pre>
</td>
</tr>
<tr class="tightenable"><th>unix line-ends, ff=mac</th>
<td><pre class="tightenable top bottom">
Line 1^JLine 2^J</pre>
</td>
</tr>
<tr class="tightenable"><th>unix line-ends, ff=dos</th>
<td><pre class="tightenable top bottom">
Line 1
Line 2</pre>
</td>
</tr>
<tr class="tightenable"><th>dos line-ends, ff=unix</th>
<td><pre class="tightenable top bottom">
Line 1^M
Line 2^M</pre>
</td>
</tr>
<tr class="tightenable"><th>dos line-ends, ff=mac</th>
<td><pre class="tightenable top bottom">
Line 1
^JLine 2
^J</pre>
</td>
</tr>
<tr class="tightenable"><th>mac line-ends, ff=unix</th>
<td><pre class="tightenable top bottom">
Line 1^MLine 2^M</pre>
</td>
</tr>
<tr class="tightenable"><th>mac line-ends, ff=dos</th>
<td><pre class="tightenable top bottom">
Line 1^MLine 2^M</pre>
</td>
</tr>
</table>
<h4>Fixing Detection Problems</h4>
<p class="tightenable bottom">If your file has consistent line endings throughout, but you have had a <b>'ff'</b> detection problem, the best fix is to force Vim to use the correct format with the :e command:</p>
<pre class="tightenable top">
:e ++ff=mac</pre>
<h4>Fixing Inconsistent Line Endings</h4>
<p class="tightenable">If you have extra leading or trailing characters (^M in unix or ^J in mac), use <b>:%s/\r//</b> to remove them.  If you have long lines (mac line-ends with ff=dos or unix, unix line ends with ff=mac), use <b>:%s/\r/\r/g</b> to replace the wrong line-ends with the correct line-ends.  If you are curious, the reasoning behind this methodology appears below.</p>
<h4>The Nitty-Gritty</h4>
<p class="tightenable">:substitute can be tricky when dealing with CR and NL.  The problem stems from the fact that Vim uses NL <b>in memory</b> to represent a Nul character (see :help NL-used-for-Nul).  The result of this is that unexpected things tend to happen when you try to modify line-endings using :s.  Vim help says that \r matches CR and \n matches an end-of-line.  In fact, when you use :s, \r will match CR <b>or</b> LF, depending on the fileformat!  Basically, it matches whichever control character (^M or ^J) you see in the editor window.  Furthermore, in the replace pattern, \n will expand to a LF, which then gets interpreted as... a Nul! (see :help sub-replace-special). Fortunately, when \r is used in the replace pattern, it is interpreted as a line-end, which will then display (and get written) as desired.</p>
<p class="tightenable">Article by 
            [1] => cached_wikilink Object
                (
                    [_page] => Tofer
                )

            [2] => .  Questions? Comments?  Contact me in #vim or send gmail to chagnon.</p>
<hr />
<p class="tightenable">Thanks Tofer, great article!  Here's a 
            [3] => cached_externallink Object
                (
                    [_url] => http://www.vim.org/tips/tip.php?tip_id=736
                    [_label] => vim tip
                )

            [4] =>  that implements the display of non-native fileformat in the statusline.<br />-- 
            [5] => cached_wikilink Object
                (
                    [_page] => GrantBow
                )

            [6] => </p>
<hr />
<p class="tightenable bottom">Excellent article. Forcing the file format (:e ++ff=mac)  did the trick for me. I knew it was a mac-file, but  ff=mac never seemed to change anything. I've been looking for this solution quite a while now ... Thanks-- cmasc</p>
</div>

        )

    [_description] => 'fileformat' ('ff' for short) controls the way that Vim handles different line-ending sequences. Vim recognizes three file formats: unix, dos, and mac.  Each of these file formats differs in the line-ending character sequences used on disk.  Unix uses a LF (line feed; ^J or 0x0A), Mac uses a CR (carriage return; ^M or 0x0D), and Dos uses CRLF (^M^J or 0x0D0A).
)