End of Line Conversion
======================

EOL conversion is provided as a content filter where Bazaar internally
stores a canonical format but outputs a convenience format. See
``bzr help content-filters`` for general information about using these.

Note: Content filtering is only supported in recently added formats,
e.g. --development-wt5 and the (pending) CHK format.

EOL conversion needs to be enabled for selected branches and files using
rules. See ``bzr help rules`` for general information on defining rules.

To configure which files to filter, set ``eol`` to one of the values below.

  ============== ======================= ==================================
  Value          Commit newlines as      On checkout, convert newlines to
  ============== ======================= ==================================
  lf             lf                      crlf on Windows, lf otherwise
  -------------- ----------------------- ----------------------------------
  crlf           crlf                    crlf on Windows, lf otherwise
  -------------- ----------------------- ----------------------------------
  lf-always      lf                      lf
  -------------- ----------------------- ----------------------------------
  crlf-always    crlf                    crlf
  -------------- ----------------------- ----------------------------------
  exact          exactly as in file      No conversion
  ============== ======================= ==================================

To summarize, the ``eol`` value specfies how to **store** the file - Bazaar
will checkout files matching either ``lf`` or ``crlf`` using your native
platform conventions. On some occasions, it is necessary to force a
particular convention or to ensure no conversion is done - ``lf-always``,
``crlf-always`` and ``exact`` are useful then.

Note: For safety reasons, no conversion is applied to any file where a null
character is detected in the file.

Here is the suggested rule for users on Windows working on a cross-platform
project:

  [name *]
  eol = lf

For developers working on a project using Windows newline conventions as
the project standard, this rule is suggested:

  [name *]
  eol = crlf

To override the conversion for certain files, give more explicit patterns
earlier in the rules file. For example:

  [name *.bat]
  eol = crlf

  [name *]
  eol = lf

This will store ``*.bat`` files using Windows (``\r\n``) conventions and
remaining files using Linux/Unix (``\n``) conventions, but all files will be
checked out with ``\r\n`` newlines on Windows and ``\n`` newlines on other
platforms.

If your working tree is on a network drive shared by users on different
operating systems, you typically want to force certain conventions for
certain files. In that way, if a file is created with the wrong line
endings, it gets committed correctly and gets checked out correctly.
For example:

  [name *.bat]
  eol = crlf-always

  [name *.sh]
  eol = lf-always

  [name *]
  eol = lf

If you have sample test data that deliberately has text files with mixed
newline conventions, you can ask for those to be left alone by combining
rule ordering and ``exact`` like this:

  [name test_data/]
  eol = exact

  [name *]
  eol = lf