## Please edit system and help pages ONLY in the moinmaster wiki! For more
## information, please see MoinMaster:MoinPagesEditorGroup.
##master-page:Unknown-Page
##master-date:Unknown-Date
##acl MoinPagesEditorGroup:read,write,delete,revert All:read
#format wiki
#language en

<<Include(A:style)>>

== Encode and decode filters ==

/!\ This is an [[UnlovedFeatures|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 <<FootNote(For full keyword support the [:KeywordExtension] is recommended, as filters lead to incorrect expansions with certain commands (update etc.))>>.  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 ===
{{{
[encode]
# convert files to unix line ending conventions on checkin
**.txt = tempfile: dos2unix -n INFILE OUTFILE

[decode]
# convert files to windows line ending conventions when writing
# them to the working dir
**.txt = tempfile: unix2dos -n INFILE OUTFILE

----