##// END OF EJS Templates
doc: add note about pattern rooted/unrooted cases to "hgignore" and "patterns"...
FUJIWARA Katsunori -
r16504:e3c7ca15 stable
parent child Browse files
Show More
@@ -1,80 +1,84 b''
1 Synopsis
1 Synopsis
2 --------
2 --------
3
3
4 The Mercurial system uses a file called ``.hgignore`` in the root
4 The Mercurial system uses a file called ``.hgignore`` in the root
5 directory of a repository to control its behavior when it searches
5 directory of a repository to control its behavior when it searches
6 for files that it is not currently tracking.
6 for files that it is not currently tracking.
7
7
8 Description
8 Description
9 -----------
9 -----------
10
10
11 The working directory of a Mercurial repository will often contain
11 The working directory of a Mercurial repository will often contain
12 files that should not be tracked by Mercurial. These include backup
12 files that should not be tracked by Mercurial. These include backup
13 files created by editors and build products created by compilers.
13 files created by editors and build products created by compilers.
14 These files can be ignored by listing them in a ``.hgignore`` file in
14 These files can be ignored by listing them in a ``.hgignore`` file in
15 the root of the working directory. The ``.hgignore`` file must be
15 the root of the working directory. The ``.hgignore`` file must be
16 created manually. It is typically put under version control, so that
16 created manually. It is typically put under version control, so that
17 the settings will propagate to other repositories with push and pull.
17 the settings will propagate to other repositories with push and pull.
18
18
19 An untracked file is ignored if its path relative to the repository
19 An untracked file is ignored if its path relative to the repository
20 root directory, or any prefix path of that path, is matched against
20 root directory, or any prefix path of that path, is matched against
21 any pattern in ``.hgignore``.
21 any pattern in ``.hgignore``.
22
22
23 For example, say we have an untracked file, ``file.c``, at
23 For example, say we have an untracked file, ``file.c``, at
24 ``a/b/file.c`` inside our repository. Mercurial will ignore ``file.c``
24 ``a/b/file.c`` inside our repository. Mercurial will ignore ``file.c``
25 if any pattern in ``.hgignore`` matches ``a/b/file.c``, ``a/b`` or ``a``.
25 if any pattern in ``.hgignore`` matches ``a/b/file.c``, ``a/b`` or ``a``.
26
26
27 In addition, a Mercurial configuration file can reference a set of
27 In addition, a Mercurial configuration file can reference a set of
28 per-user or global ignore files. See the ``ignore`` configuration
28 per-user or global ignore files. See the ``ignore`` configuration
29 key on the ``[ui]`` section of :hg:`help config` for details of how to
29 key on the ``[ui]`` section of :hg:`help config` for details of how to
30 configure these files.
30 configure these files.
31
31
32 To control Mercurial's handling of files that it manages, many
32 To control Mercurial's handling of files that it manages, many
33 commands support the ``-I`` and ``-X`` options; see
33 commands support the ``-I`` and ``-X`` options; see
34 :hg:`help <command>` and :hg:`help patterns` for details.
34 :hg:`help <command>` and :hg:`help patterns` for details.
35
35
36 Syntax
36 Syntax
37 ------
37 ------
38
38
39 An ignore file is a plain text file consisting of a list of patterns,
39 An ignore file is a plain text file consisting of a list of patterns,
40 with one pattern per line. Empty lines are skipped. The ``#``
40 with one pattern per line. Empty lines are skipped. The ``#``
41 character is treated as a comment character, and the ``\`` character
41 character is treated as a comment character, and the ``\`` character
42 is treated as an escape character.
42 is treated as an escape character.
43
43
44 Mercurial supports several pattern syntaxes. The default syntax used
44 Mercurial supports several pattern syntaxes. The default syntax used
45 is Python/Perl-style regular expressions.
45 is Python/Perl-style regular expressions.
46
46
47 To change the syntax used, use a line of the following form::
47 To change the syntax used, use a line of the following form::
48
48
49 syntax: NAME
49 syntax: NAME
50
50
51 where ``NAME`` is one of the following:
51 where ``NAME`` is one of the following:
52
52
53 ``regexp``
53 ``regexp``
54 Regular expression, Python/Perl syntax.
54 Regular expression, Python/Perl syntax.
55 ``glob``
55 ``glob``
56 Shell-style glob.
56 Shell-style glob.
57
57
58 The chosen syntax stays in effect when parsing all patterns that
58 The chosen syntax stays in effect when parsing all patterns that
59 follow, until another syntax is selected.
59 follow, until another syntax is selected.
60
60
61 Neither glob nor regexp patterns are rooted. A glob-syntax pattern of
61 Neither glob nor regexp patterns are rooted. A glob-syntax pattern of
62 the form ``*.c`` will match a file ending in ``.c`` in any directory,
62 the form ``*.c`` will match a file ending in ``.c`` in any directory,
63 and a regexp pattern of the form ``\.c$`` will do the same. To root a
63 and a regexp pattern of the form ``\.c$`` will do the same. To root a
64 regexp pattern, start it with ``^``.
64 regexp pattern, start it with ``^``.
65
65
66 .. note::
67 Patterns specified in other than ``.hgignore`` are always rooted.
68 Please see :hg:`help patterns` for details.
69
66 Example
70 Example
67 -------
71 -------
68
72
69 Here is an example ignore file. ::
73 Here is an example ignore file. ::
70
74
71 # use glob syntax.
75 # use glob syntax.
72 syntax: glob
76 syntax: glob
73
77
74 *.elc
78 *.elc
75 *.pyc
79 *.pyc
76 *~
80 *~
77
81
78 # switch to regexp syntax.
82 # switch to regexp syntax.
79 syntax: regexp
83 syntax: regexp
80 ^\.pc/
84 ^\.pc/
@@ -1,53 +1,57 b''
1 Mercurial accepts several notations for identifying one or more files
1 Mercurial accepts several notations for identifying one or more files
2 at a time.
2 at a time.
3
3
4 By default, Mercurial treats filenames as shell-style extended glob
4 By default, Mercurial treats filenames as shell-style extended glob
5 patterns.
5 patterns.
6
6
7 Alternate pattern notations must be specified explicitly.
7 Alternate pattern notations must be specified explicitly.
8
8
9 .. note::
10 Patterns specified in ``.hgignore`` are not rooted. Please see
11 :hg:`help hgignore` for details.
12
9 To use a plain path name without any pattern matching, start it with
13 To use a plain path name without any pattern matching, start it with
10 ``path:``. These path names must completely match starting at the
14 ``path:``. These path names must completely match starting at the
11 current repository root.
15 current repository root.
12
16
13 To use an extended glob, start a name with ``glob:``. Globs are rooted
17 To use an extended glob, start a name with ``glob:``. Globs are rooted
14 at the current directory; a glob such as ``*.c`` will only match files
18 at the current directory; a glob such as ``*.c`` will only match files
15 in the current directory ending with ``.c``.
19 in the current directory ending with ``.c``.
16
20
17 The supported glob syntax extensions are ``**`` to match any string
21 The supported glob syntax extensions are ``**`` to match any string
18 across path separators and ``{a,b}`` to mean "a or b".
22 across path separators and ``{a,b}`` to mean "a or b".
19
23
20 To use a Perl/Python regular expression, start a name with ``re:``.
24 To use a Perl/Python regular expression, start a name with ``re:``.
21 Regexp pattern matching is anchored at the root of the repository.
25 Regexp pattern matching is anchored at the root of the repository.
22
26
23 To read name patterns from a file, use ``listfile:`` or ``listfile0:``.
27 To read name patterns from a file, use ``listfile:`` or ``listfile0:``.
24 The latter expects null delimited patterns while the former expects line
28 The latter expects null delimited patterns while the former expects line
25 feeds. Each string read from the file is itself treated as a file
29 feeds. Each string read from the file is itself treated as a file
26 pattern.
30 pattern.
27
31
28 Plain examples::
32 Plain examples::
29
33
30 path:foo/bar a name bar in a directory named foo in the root
34 path:foo/bar a name bar in a directory named foo in the root
31 of the repository
35 of the repository
32 path:path:name a file or directory named "path:name"
36 path:path:name a file or directory named "path:name"
33
37
34 Glob examples::
38 Glob examples::
35
39
36 glob:*.c any name ending in ".c" in the current directory
40 glob:*.c any name ending in ".c" in the current directory
37 *.c any name ending in ".c" in the current directory
41 *.c any name ending in ".c" in the current directory
38 **.c any name ending in ".c" in any subdirectory of the
42 **.c any name ending in ".c" in any subdirectory of the
39 current directory including itself.
43 current directory including itself.
40 foo/*.c any name ending in ".c" in the directory foo
44 foo/*.c any name ending in ".c" in the directory foo
41 foo/**.c any name ending in ".c" in any subdirectory of foo
45 foo/**.c any name ending in ".c" in any subdirectory of foo
42 including itself.
46 including itself.
43
47
44 Regexp examples::
48 Regexp examples::
45
49
46 re:.*\.c$ any name ending in ".c", anywhere in the repository
50 re:.*\.c$ any name ending in ".c", anywhere in the repository
47
51
48 File examples::
52 File examples::
49
53
50 listfile:list.txt read list from list.txt with one file pattern per line
54 listfile:list.txt read list from list.txt with one file pattern per line
51 listfile0:list.txt read list from list.txt with null byte delimiters
55 listfile0:list.txt read list from list.txt with null byte delimiters
52
56
53 See also :hg:`help filesets`.
57 See also :hg:`help filesets`.
General Comments 0
You need to be logged in to leave comments. Login now