Content filter sample: eol plugin

[Martin Pool]

On Sat, May 17, 2008 at 1:43 AM, Ian Clatworthy
<ian.clatworthy at internode.on.net> wrote:
> For those interested, I've attached the README.txt and core code for the
> upcoming eol (end of line) plugin. This shows two important things:
>
> 1. How easy it is to write and register content filters.
>
> 2. How rule-based properties are used to configure it.
>
> DO NOT RUN THIS code and tell me it's broken! I'll make a proper branch
> or patch (if we think it ought to be a standard plugin) available soon
> once I've tested it further.
>
> That warning aside, I hope people find it interesting. :-)
>
> Ian C.
>
> bzr-eol: End Of Line conversion plugin
> ======================================
>
> Overview
> --------
>
> This plugin adds EOL conversion to selected files. This makes it easier to
> work on text files in projects where developers are on multiple platforms or
> developing for multiple platforms.
>
>
> Installation
> ------------
>
> The easiest way to install this plugin is to either copy or symlink the
> directory into your ~/.bazaar/plugins directory. Be sure to rename the
> directory to eol (instead of bzr-eol).
>
> See http://bazaar-vcs.org/UsingPlugins for other options such as
> using the BZR_PLUGIN_PATH environment variable.
>
>
> Testing
> -------
>
> To test the plugin after installation:
>
>    bzr selftest eol
>
>
> Documentation
> -------------
>
> 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.
>
> EOL conversion needs to be enabled for selected branches and files using
> rules. Default rules for all branches can be defined in ``bazaar.rules``.
> Alternatively, branch-specific rules can be defined in ``branch.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
>  ====== ======================= ========================================
>  exact  exactly as in file      No conversion
>  ------ ----------------------- ----------------------------------------
>  native lf                      crlf on Windows, otherwise lf
>  ------ ----------------------- ----------------------------------------
>  dos    crlf                    crlf on Windows, otherwise lf
>  ====== ======================= ========================================
>
> Note: For safety reasons, no conversion is applied to any file where a null
> character is detected in the file.

I think we should choose _either_ to call the modes by the line ending
convention (crlf) or by the platform where they are typically used
(dos) but not some of one and some of the other.  Naming by platform
is probably more recognizable, but does mean there's no obvious name
for just "cr" ("old mac"?)

It seems  to me what we want is

  exact -- no changes; default
  native -- produce whatever is the normal convention for the platform
where the checkout was made; internally always stored with just lfs --
this is suitable for files in cross-platform projects that will work
with either linending
  cr -- should always have cr
  lf -- suitable for eg unix shell scripts that will be broken by
carriage returns
  crlf -- suitable for dos batch files that need carriage returns

I can see room for another option that says what to do if the working
copy is not as expected, or if it has mixed line endings - it could
either do nothing, warn, or error.  That could be added later of
course.

> Here is the suggested rule for users on Windows working on a cross-platform
> project::
>
>  [*]
>  eol = native

I see what you mean but that is a somewhat risky setting; I don't know
if anything is really safe for *.

> If you think it would be clearer, I'll rename "native" to "unix".

But this sounds really odd to me - surely "native" is only "unix" if
you are actually on unix?

-- 
Martin <http://launchpad.net/~mbp/>