Diff for "Win32TextExtension"

Win32text extension

This extension is currently being distributed along with Mercurial.

Author: Bryan O'Sullivan

Overview

Core Mercurial tracks but never modifies file content, and it is thus binary safe. The different line ending conventions traditionally used in unix and windows will thus be maintained with core Mercurial. That can give annoyances and problems in mixed environments, so traditionally unix2dos and dos2unix scripts are used to manage the mess. The win32text Mercurial extension addresses this problem.

Method

The win32text extension assumes and maintains that the repository is in unix-style, and that text files in the repository thus uses \n for newline. The extension is only used on windows to convert text files, thus the name.

When Mercurial reads text file content from the repository then the extension can filter and decode unix-style \n to windows-style \r\n - and it will warn if the repository file already has windows-style newlines. And when Mercurial commits text files to the repository then they will first be decoded from windows-style \r\n to unix-style \n.

The remaining problem is to decided which files are text files; Mercurial intentionally doesn't track that kind of meta-data.

The win32text filters are applied to files matching a pattern, and by carefully creating patterns the filters can be applied to exactly all text files in a repository. The filter specification can however not be managed by the repository, so creating complex specifications for distributed projects isn't recommended. But the filters come in two variants: A "dumb" filter which modifies anything looking like line endings in all files it is applied to, and a "clever" filter which only works on files NOT containing zero bytes. The simple heuristics used by the "clever" filter will fail in some cases, but it often works so well that it can just be applied to all files.

Note: do not change the encode or decode filter settings while you have files checked out - use hg update null to remove any working files first.

Configuration

Enable the extension in the configuration file (hgrc) and specify which filters should be used where, for example:

[extensions]
hgext.win32text=

[encode]
# Encode files that don't contain NUL characters.

** = cleverencode:

# Alternatively, you can explicitly specify each file extension that
# you want encoded (any you omit will be left untouched), like this:

# **.txt = dumbencode:


[decode]
# Decode files that don't contain NUL characters.

** = cleverdecode:

# Alternatively, you can explicitly specify each file extension that
# you want decoded (any you omit will be left untouched), like this:

# **.txt = dumbdecode:

If you apply these settings globally but wish to override them for a specific repository, use the "!" syntax in the repository hgrc file to remove the filters.

[extensions]
# Disable the extension
hgext.win32text= !

[encode]
# Disable the encoding filter
** = !

[decode]
# Disable the decoding filter
** = !

Usage

This extension doesn't require user interaction to work.

CategoryExtension CategoryWindows