#pragma section-numbers 2
= Exclude Extension =

Setup default exclude filters.

<<TableOfContents>>

== Status ==

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

''Author: '' ''Erik Zielke''

Repository: https://bitbucket.org/aragost/exclude/

Web page: ''https://bitbucket.org/aragost/exclude/src/''

== Overview ==

People sometimes have files in a working copy that they would like to distribute when cloning but where modifications should be ignored. The typical example is configuration files where a template is committed to the repository which every developer has to modify to set local paths and/or passwords.

This extension lets you setup a ''`.hgexclude`'' file with the files that should be excluded by default. The ''`.hgexclude`'' file uses the same syntax as the [[http://www.selenic.com/mercurial/hgignore.5.html|.hgignore]] file.

== Configuration ==
Configure your .hgrc to enable the extension by adding following lines:

{{{
[extensions]
exclude = ~/path/to/exclude/exclude.py
}}}

== Caveats ==

The extension works by injecting `--exclude` flags to all commands that support them. Some commands do not support excluding anything and will always operate on the entire working copy: merge is the best example. When you begin using this extension you will notice that `hg merge` aborts with a message about the working copy being dirty even though `hg status` reports no changes. This is because `hg status` excludes the modified file. A smarter version of the extension would know to shelve the modified files before doing the merge.

== Alternatives ==

A better way to do this is to stop versioning the real file and instead version a template under a different name. So you add and commit ''`config.template`'' and configure your application so that will read ''`config.template`'' first and then read ''`config`'' to overwrite any settings. The ''`config`'' file holds the local configuration and is added to the ''`.hgignore`'' file.

This trick requires that you can either change your application to read both files, or that you can include one configuration file from within another. Many configuration files have support for such optional inclusion for precisely this reason.

----
CategoryExtensionsByOthers