|
|
Synopsis
|
|
|
========
|
|
|
|
|
|
The Mercurial system uses a file called ``.hgignore`` in the root
|
|
|
directory of a repository to control its behavior when it searches
|
|
|
for files that it is not currently tracking.
|
|
|
|
|
|
Description
|
|
|
===========
|
|
|
|
|
|
The working directory of a Mercurial repository will often contain
|
|
|
files that should not be tracked by Mercurial. These include backup
|
|
|
files created by editors and build products created by compilers.
|
|
|
These files can be ignored by listing them in a ``.hgignore`` file in
|
|
|
the root of the working directory. The ``.hgignore`` file must be
|
|
|
created manually. It is typically put under version control, so that
|
|
|
the settings will propagate to other repositories with push and pull.
|
|
|
|
|
|
An untracked file is ignored if its path relative to the repository
|
|
|
root directory, or any prefix path of that path, is matched against
|
|
|
any pattern in ``.hgignore``.
|
|
|
|
|
|
For example, say we have an untracked file, ``file.c``, at
|
|
|
``a/b/file.c`` inside our repository. Mercurial will ignore ``file.c``
|
|
|
if any pattern in ``.hgignore`` matches ``a/b/file.c``, ``a/b`` or ``a``.
|
|
|
|
|
|
In addition, a Mercurial configuration file can reference a set of
|
|
|
per-user or global ignore files. See the ``ignore`` configuration
|
|
|
key on the ``[ui]`` section of :hg:`help config` for details of how to
|
|
|
configure these files.
|
|
|
|
|
|
To control Mercurial's handling of files that it manages, many
|
|
|
commands support the ``-I`` and ``-X`` options; see
|
|
|
:hg:`help <command>` and :hg:`help patterns` for details.
|
|
|
|
|
|
Files that are already tracked are not affected by .hgignore, even
|
|
|
if they appear in .hgignore. An untracked file X can be explicitly
|
|
|
added with :hg:`add X`, even if X would be excluded by a pattern
|
|
|
in .hgignore.
|
|
|
|
|
|
Syntax
|
|
|
======
|
|
|
|
|
|
An ignore file is a plain text file consisting of a list of patterns,
|
|
|
with one pattern per line. Empty lines are skipped. The ``#``
|
|
|
character is treated as a comment character, and the ``\`` character
|
|
|
is treated as an escape character.
|
|
|
|
|
|
Mercurial supports several pattern syntaxes. The default syntax used
|
|
|
is Python/Perl-style regular expressions.
|
|
|
|
|
|
To change the syntax used, use a line of the following form::
|
|
|
|
|
|
syntax: NAME
|
|
|
|
|
|
where ``NAME`` is one of the following:
|
|
|
|
|
|
``regexp``
|
|
|
Regular expression, Python/Perl syntax.
|
|
|
``glob``
|
|
|
Shell-style glob.
|
|
|
``rootglob``
|
|
|
A variant of ``glob`` that is rooted (see below).
|
|
|
|
|
|
The chosen syntax stays in effect when parsing all patterns that
|
|
|
follow, until another syntax is selected.
|
|
|
|
|
|
Neither ``glob`` nor regexp patterns are rooted. A glob-syntax
|
|
|
pattern of the form ``*.c`` will match a file ending in ``.c`` in any
|
|
|
directory, and a regexp pattern of the form ``\.c$`` will do the
|
|
|
same. To root a regexp pattern, start it with ``^``. To get the same
|
|
|
effect with glob-syntax, you have to use ``rootglob``.
|
|
|
|
|
|
Subdirectories can have their own .hgignore settings by adding
|
|
|
``subinclude:path/to/subdir/.hgignore`` to the root ``.hgignore``. See
|
|
|
:hg:`help patterns` for details on ``subinclude:`` and ``include:``.
|
|
|
|
|
|
.. note::
|
|
|
|
|
|
Patterns specified in other than ``.hgignore`` are always rooted.
|
|
|
Please see :hg:`help patterns` for details.
|
|
|
|
|
|
Example
|
|
|
=======
|
|
|
|
|
|
Here is an example ignore file. ::
|
|
|
|
|
|
# use glob syntax.
|
|
|
syntax: glob
|
|
|
|
|
|
*.elc
|
|
|
*.pyc
|
|
|
*~
|
|
|
|
|
|
# switch to regexp syntax.
|
|
|
syntax: regexp
|
|
|
^\.pc/
|
|
|
|
|
|
Debugging
|
|
|
=========
|
|
|
|
|
|
Use the ``debugignore`` command to see if and why a file is ignored, or to
|
|
|
see the combined ignore pattern. See :hg:`help debugignore` for details.
|
|
|
|
