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