| 1 |
<?xml version="1.0" encoding="utf-8"?> |
| 2 |
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| 3 |
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> |
| 4 |
<head> |
| 5 |
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> |
| 6 |
<meta name="generator" content="Docutils 0.21.2: https://docutils.sourceforge.io/" /> |
| 7 |
<title>Syntax for Mercurial Ignore Files</title> |
| 8 |
<link rel="stylesheet" href="../style.css" type="text/css" /> |
| 9 |
</head> |
| 10 |
<body> |
| 11 |
<div class="document" id="syntax-for-mercurial-ignore-files"> |
| 12 |
<span id="topic-hgignore"></span> |
| 13 |
<h1 class="title">Syntax for Mercurial Ignore Files</h1> |
| 14 |
|
| 15 |
<div class="contents htmlonly topic" id="contents"> |
| 16 |
<p class="topic-title"><a class="reference internal" href="#top">Contents</a></p> |
| 17 |
<ul class="simple"> |
| 18 |
<li><a class="reference internal" href="#synopsis" id="toc-entry-1">Synopsis</a></li> |
| 19 |
<li><a class="reference internal" href="#description" id="toc-entry-2">Description</a></li> |
| 20 |
<li><a class="reference internal" href="#syntax" id="toc-entry-3">Syntax</a></li> |
| 21 |
<li><a class="reference internal" href="#example" id="toc-entry-4">Example</a></li> |
| 22 |
<li><a class="reference internal" href="#debugging" id="toc-entry-5">Debugging</a></li> |
| 23 |
</ul> |
| 24 |
</div> |
| 25 |
<div class="section" id="synopsis"> |
| 26 |
<span id="ignore"></span><span id="hgignore"></span><h1><a class="toc-backref" href="#contents">Synopsis</a></h1> |
| 27 |
<p>The Mercurial system uses a file called <tt class="docutils literal">.hgignore</tt> in the root |
| 28 |
directory of a repository to control its behavior when it searches |
| 29 |
for files that it is not currently tracking.</p> |
| 30 |
</div> |
| 31 |
<div class="section" id="description"> |
| 32 |
<h1><a class="toc-backref" href="#contents">Description</a></h1> |
| 33 |
<p>The working directory of a Mercurial repository will often contain |
| 34 |
files that should not be tracked by Mercurial. These include backup |
| 35 |
files created by editors and build products created by compilers. |
| 36 |
These files can be ignored by listing them in a <tt class="docutils literal">.hgignore</tt> file in |
| 37 |
the root of the working directory. The <tt class="docutils literal">.hgignore</tt> file must be |
| 38 |
created manually. It is typically put under version control, so that |
| 39 |
the settings will propagate to other repositories with push and pull.</p> |
| 40 |
<p>An untracked file is ignored if its path relative to the repository |
| 41 |
root directory, or any prefix path of that path, is matched against |
| 42 |
any pattern in <tt class="docutils literal">.hgignore</tt>.</p> |
| 43 |
<p>For example, say we have an untracked file, <tt class="docutils literal">file.c</tt>, at |
| 44 |
<tt class="docutils literal">a/b/file.c</tt> inside our repository. Mercurial will ignore <tt class="docutils literal">file.c</tt> |
| 45 |
if any pattern in <tt class="docutils literal">.hgignore</tt> matches <tt class="docutils literal">a/b/file.c</tt>, <tt class="docutils literal">a/b</tt> or <tt class="docutils literal">a</tt>.</p> |
| 46 |
<p>In addition, a Mercurial configuration file can reference a set of |
| 47 |
per-user or global ignore files. See the <tt class="docutils literal">ignore</tt> configuration |
| 48 |
key on the <tt class="docutils literal">[ui]</tt> section of <a class="reference external" href="hgrc.5.html"><tt class="docutils literal">hg help config</tt></a> for details of how to |
| 49 |
configure these files.</p> |
| 50 |
<p>To control Mercurial's handling of files that it manages, many |
| 51 |
commands support the <tt class="docutils literal"><span class="pre">-I</span></tt> and <tt class="docutils literal"><span class="pre">-X</span></tt> options; see |
| 52 |
<a class="reference external" href="hg.1.html#<command>"><tt class="docutils literal">hg help <command></tt></a> and <a class="reference external" href="topic-patterns.html"><tt class="docutils literal">hg help patterns</tt></a> for details.</p> |
| 53 |
<p>Files that are already tracked are not affected by .hgignore, even |
| 54 |
if they appear in .hgignore. An untracked file X can be explicitly |
| 55 |
added with <a class="reference external" href="hg-add.html"><tt class="docutils literal">hg add X</tt></a>, even if X would be excluded by a pattern |
| 56 |
in .hgignore.</p> |
| 57 |
</div> |
| 58 |
<div class="section" id="syntax"> |
| 59 |
<h1><a class="toc-backref" href="#contents">Syntax</a></h1> |
| 60 |
<p>An ignore file is a plain text file consisting of a list of patterns, |
| 61 |
with one pattern per line. Empty lines are skipped. The <tt class="docutils literal">#</tt> |
| 62 |
character is treated as a comment character, and the <tt class="docutils literal">\</tt> character |
| 63 |
is treated as an escape character.</p> |
| 64 |
<p>Mercurial supports several pattern syntaxes. The default syntax used |
| 65 |
is Python/Perl-style regular expressions.</p> |
| 66 |
<p>To change the syntax used, use a line of the following form:</p> |
| 67 |
<pre class="literal-block"> |
| 68 |
syntax: NAME |
| 69 |
</pre> |
| 70 |
<p>where <tt class="docutils literal">NAME</tt> is one of the following:</p> |
| 71 |
<dl class="docutils"> |
| 72 |
<dt><tt class="docutils literal">regexp</tt></dt> |
| 73 |
<dd>Regular expression, Python/Perl syntax.</dd> |
| 74 |
<dt><tt class="docutils literal">glob</tt></dt> |
| 75 |
<dd>Shell-style glob.</dd> |
| 76 |
<dt><tt class="docutils literal">rootglob</tt></dt> |
| 77 |
<dd>A variant of <tt class="docutils literal">glob</tt> that is rooted (see below).</dd> |
| 78 |
</dl> |
| 79 |
<p>The chosen syntax stays in effect when parsing all patterns that |
| 80 |
follow, until another syntax is selected.</p> |
| 81 |
<p>Neither <tt class="docutils literal">glob</tt> nor regexp patterns are rooted. A glob-syntax |
| 82 |
pattern of the form <tt class="docutils literal">*.c</tt> will match a file ending in <tt class="docutils literal">.c</tt> in any |
| 83 |
directory, and a regexp pattern of the form <tt class="docutils literal">\.c$</tt> will do the |
| 84 |
same. To root a regexp pattern, start it with <tt class="docutils literal">^</tt>. To get the same |
| 85 |
effect with glob-syntax, you have to use <tt class="docutils literal">rootglob</tt>.</p> |
| 86 |
<p>Subdirectories can have their own .hgignore settings by adding |
| 87 |
<tt class="docutils literal"><span class="pre">subinclude:path/to/subdir/.hgignore</span></tt> to the root <tt class="docutils literal">.hgignore</tt>. See |
| 88 |
<a class="reference external" href="topic-patterns.html"><tt class="docutils literal">hg help patterns</tt></a> for details on <tt class="docutils literal">subinclude:</tt> and <tt class="docutils literal">include:</tt>.</p> |
| 89 |
<div class="admonition note"> |
| 90 |
<p class="first admonition-title">Note</p> |
| 91 |
<p class="last">Patterns specified in other than <tt class="docutils literal">.hgignore</tt> are always rooted. |
| 92 |
Please see <a class="reference external" href="topic-patterns.html"><tt class="docutils literal">hg help patterns</tt></a> for details.</p> |
| 93 |
</div> |
| 94 |
</div> |
| 95 |
<div class="section" id="example"> |
| 96 |
<h1><a class="toc-backref" href="#contents">Example</a></h1> |
| 97 |
<p>Here is an example ignore file.</p> |
| 98 |
<pre class="literal-block"> |
| 99 |
# use glob syntax. |
| 100 |
syntax: glob |
| 101 |
|
| 102 |
*.elc |
| 103 |
*.pyc |
| 104 |
*~ |
| 105 |
|
| 106 |
# switch to regexp syntax. |
| 107 |
syntax: regexp |
| 108 |
^\.pc/ |
| 109 |
</pre> |
| 110 |
</div> |
| 111 |
<div class="section" id="debugging"> |
| 112 |
<h1><a class="toc-backref" href="#contents">Debugging</a></h1> |
| 113 |
<p>Use the <tt class="docutils literal">debugignore</tt> command to see if and why a file is ignored, or to |
| 114 |
see the combined ignore pattern. See <a class="reference external" href="hg.1.html#debugignore"><tt class="docutils literal">hg help debugignore</tt></a> for details.</p> |
| 115 |
</div> |
| 116 |
</div> |
| 117 |
</body> |
| 118 |
</html> |