EOL Extension

Automatic management of EOL conversion.

1. Status

This extension is distributed with Mercurial 1.5.4.

Author: Martin Geisler mg@lazybytes.net

2. Overview

Different platforms have different conventions for representing line endings in text files:

When working with people on different operating systems, it can therefore be desirable to be able to checkout text files with the operating system native line ending representation. This extension lets you specify how end of lines (EOLs) are converted between the repository representation and the working copy representation.

3. Configuration

Configure your .hgrc to enable the extension by adding following lines:

[extensions]
eol =

Important: After you've finished your EOL configuration you should make a clean checkout. This is necessary since the EOL extension only converts line endings when hg update is ran (and then only on files that are modified by this command). Line endings are not converted when committing a file. The easiest way to do a clean checkout is to delete all files from your working copy (use hg co -C null, don't use hg remove for this) - except the .hg directory of course. Then run hg update -C to check this files out again - now with the correct line endings.

3.1. Per-repository configuration

Then create a file called .hgeol in the root of your working copy. This file contains patterns that tells the extension how files should be converted back and forth between the working copy and the repository. If this file is missing, the extension will not convert any files. The patterns look like this:

[patterns]
**.py = native
**.vcproj = CRLF
**.txt = native
Makefile = LF
**.jpg = BIN

This example specifies the following rules:

The native format must know how to convert the operating system native encoding back to the repository encoding. The default repository encoding is LF, but this is configurable too. Put the following section into .hgeol to override the default:

[repository]
native = CRLF

You should put the .hgeol file under version control so that all members of your project use the same rules.

3.2. Per-user configuration

The extension will normally not touch files in which the EOLs are not consistent, that is, files containing both \r\n and \n line endings. This is on the assumption that the user knows what he or she is doing and has put in the mixed line endings on purpose.

If you want to convert such files anyway, then set

[eol]
only-consistent = False

in your .hgrc file.

Please see hg help eol for help matching your version of the extension and see hg help patterns for more information on the glob patterns used.

4. Hooks

TBD

5. Migrating from win32text to eol

In earlier versions of Mercurial, the conversion of line endings was done with the Win32TextExtension. Please see the page MigratingFromWin32TextToEol for a guide for migrating from win32text to eol.

6. Troubleshooting

'abort: local changes found' but hg diff does NOT show any changes: remove all tracked files from the repository and check them out afresh by running hg co -C null; hg co tip. You may still get 'abort: local changes found', but now hg diff should show you the changes it's complaining about (see next paragraph). This problem can occur if the working copy of a file and the repository's internal copy both have the same line endings, but they are the WRONG line endings according to the .hgeol file.

'abort: local changes found' and hg diff DOES show the changes: assuming you've enabled the eol extension and run the hg co -C null; hg co tip step, this is probably because the repository's INTERNAL copy of the file(s) shown in the diff has the WRONG line endings. This can happen if the file was committed to the repository with these line endings by someone who hasn't turned on the eol extension, or by someone before your project started using the eol extension. If the changeset adding the wrong line endings was created by you and it has NOT yet been transferred to a shared repository, then you can use the qimport command to change the changeset to use the correct line endings. If the changeset has been shared, then probably the best thing to do is to commit the changes with a message along the lines of "fix line endings" (or alternatively reevaluate whether the rules in the repository's .hgeol file are even correct).


CategoryBundledExtension