#pragma section-numbers 2
= KillBom =

This Mercurial extension will remove the BOM from all Unicode files. Resulting file will be UTF-8 and without pesky BOM bytes.


<<TableOfContents>>


== Status ==

'''This extension is not distributed with Mercurial.'''

''Author: '' ''Josip Medved''

Repository: ''https://bitbucket.org/jmedved/hg-killbom''


== Overview ==

This extension will modify all Unicode files with BOM (byte order mark) and convert them to BOM-less UTF-8. This comes especially handy when dealing with Microsoft's Visual Studio that is really UTF-8 BOM happy.

Extensions adds two commands (`killbom`, `checkbom`) and hooks into the commit process.


== Configuration ==

To use it just add following in the `hgrc` or global Mercurial settings file:

{{{
[extensions]
killbom = /path/to/killbom.py

[killbom]
action = modify
extensions = utf-8 utf-16le utf-16be utf-32le utf-32be
maxsize = 1024
}}}


 * `extensions` is a list of all Unicode encodings that will be recognized.
 * `maxsize` is maximum file size that will be processed (in kilobytes).
 * `action` can be either `modify` (default), `verify`, or `ignore`:
  * `modify` - files will be adjusted before the commit
  * `verify` - commit will be aborted if there are Unicode files with BOM but files won't be modified
  * `ignore` - no action will be taken


== Usage ==

Using `killbom` command will remove Unicode BOM from all modified and newly added files:

{{{
hg killbom [options]

options:
  -8 --utf8only  removes only UTF-8 BOM signature
  -a --all       check all files in the repository
}}}


To just verify whether all files are BOM free, you would use `checkbom` command:

{{{
hg checkbom [options]

options:
  -8 --utf8only  checks for only UTF-8 BOM signature
  -a --all       check all files in the repository
}}}


In addition there are three hooks. On `pretxncommit` and `pretxnchangegroup` extension will verify whether all Unicode files are BOM-free and it will stop commit if they are not. On `precommit` extension will modify files and remove BOM.

----
CategoryExtensionsByOthers