Debian Codegraph @

doc/html/topic-hgignore.html

raw
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#&lt;command&gt;"><tt class="docutils literal">hg help &lt;command&gt;</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>