{i} This page does not meet our wiki style guidelines. Please help improve this page by cleaning up its formatting.

Encode and decode filters

/!\ This is an unloved feature

The .hgrc file has two sections [encode] and [decode]. These sections can be used to implement canonicalization of line endings (equivalent to Subversion eol-style:native) for certain files or RCS-style keyword replacement 1. These sections specify filters that can apply to specified files.

Warning: Encode/decode filters do not play nice with MqExtension or import/export if you ever want to apply patches to encoded files.

Filters consist of a filter pattern followed by a filter command. Filter patterns are globs by default, rooted at the repository root. For example, to match any file ending in ".txt" in the root directory only, use the pattern "*.txt". To match any file ending in ".c" anywhere in the repository, use the pattern "**.c".

The filter command can start with a specifier, either "pipe:" or "tempfile:". If no specifier is given, "pipe:" is used by default.

A "pipe:" command must accept data on stdin and return the transformed data on stdout.

Pipe example

[encode]
# uncompress gzip files on checkin to improve delta compression
# note: not necessarily a good idea, just an example
*.gz = pipe: gunzip

[decode]
# recompress gzip files when writing them to the working dir (we
# can safely omit "pipe:", because it's the default)
*.gz = gzip

A "tempfile:" command is a template. The string INFILE is replaced with the name of a temporary file that contains the data to be filtered by the command. The string OUTFILE is replaced with the name of an empty temporary file, where the filtered data must be written by the command.

/!\ Windows systems: The tempfile mechanism is recommended for Windows systems, where the standard shell I/O redirection operators often have strange effects. In particular, if you are doing line ending conversion on Windows using the popular dos2unix and unix2dos programs, you must use the tempfile mechanism, as using pipes will corrupt the contents of your files.

Tempfile example

  1. For full keyword support the [:KeywordExtension] is recommended, as filters lead to incorrect expansions with certain commands (update etc.) (1)

EncodeDecodeFilter (last edited 2012-10-25 20:11:27 by mpm)