annotate mercurial/helptext/hgignore.txt @ 50896:b2b8c25f9462

hgwebmod: use sysstr to check for attribute presence We do not need bytes here.
author Pierre-Yves David <pierre-yves.david@octobus.net>
date Wed, 30 Aug 2023 13:28:09 +0200
parents b77d5b568496
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
14044
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
1 Synopsis
17267
979b107eaea2 doc: unify section level between help topics
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 17116
diff changeset
2 ========
14044
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
3
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
4 The Mercurial system uses a file called ``.hgignore`` in the root
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
5 directory of a repository to control its behavior when it searches
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
6 for files that it is not currently tracking.
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
7
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
8 Description
17267
979b107eaea2 doc: unify section level between help topics
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 17116
diff changeset
9 ===========
14044
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
10
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
11 The working directory of a Mercurial repository will often contain
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
12 files that should not be tracked by Mercurial. These include backup
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
13 files created by editors and build products created by compilers.
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
14 These files can be ignored by listing them in a ``.hgignore`` file in
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
15 the root of the working directory. The ``.hgignore`` file must be
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
16 created manually. It is typically put under version control, so that
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
17 the settings will propagate to other repositories with push and pull.
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
18
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
19 An untracked file is ignored if its path relative to the repository
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
20 root directory, or any prefix path of that path, is matched against
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
21 any pattern in ``.hgignore``.
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
22
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
23 For example, say we have an untracked file, ``file.c``, at
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
24 ``a/b/file.c`` inside our repository. Mercurial will ignore ``file.c``
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
25 if any pattern in ``.hgignore`` matches ``a/b/file.c``, ``a/b`` or ``a``.
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
26
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
27 In addition, a Mercurial configuration file can reference a set of
14668
2d6f1b2c6a82 help/hgignore: refer to the builtin help instead of external URLs
Wagner Bruna <wbruna@softwareexpress.com.br>
parents: 14044
diff changeset
28 per-user or global ignore files. See the ``ignore`` configuration
2d6f1b2c6a82 help/hgignore: refer to the builtin help instead of external URLs
Wagner Bruna <wbruna@softwareexpress.com.br>
parents: 14044
diff changeset
29 key on the ``[ui]`` section of :hg:`help config` for details of how to
2d6f1b2c6a82 help/hgignore: refer to the builtin help instead of external URLs
Wagner Bruna <wbruna@softwareexpress.com.br>
parents: 14044
diff changeset
30 configure these files.
14044
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
31
14668
2d6f1b2c6a82 help/hgignore: refer to the builtin help instead of external URLs
Wagner Bruna <wbruna@softwareexpress.com.br>
parents: 14044
diff changeset
32 To control Mercurial's handling of files that it manages, many
2d6f1b2c6a82 help/hgignore: refer to the builtin help instead of external URLs
Wagner Bruna <wbruna@softwareexpress.com.br>
parents: 14044
diff changeset
33 commands support the ``-I`` and ``-X`` options; see
2d6f1b2c6a82 help/hgignore: refer to the builtin help instead of external URLs
Wagner Bruna <wbruna@softwareexpress.com.br>
parents: 14044
diff changeset
34 :hg:`help <command>` and :hg:`help patterns` for details.
14044
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
35
17116
d8c76c82d012 help: explain effect of .hgignore on tracked files
Adrian Buehlmann <adrian@cadifra.com>
parents: 16504
diff changeset
36 Files that are already tracked are not affected by .hgignore, even
d8c76c82d012 help: explain effect of .hgignore on tracked files
Adrian Buehlmann <adrian@cadifra.com>
parents: 16504
diff changeset
37 if they appear in .hgignore. An untracked file X can be explicitly
d8c76c82d012 help: explain effect of .hgignore on tracked files
Adrian Buehlmann <adrian@cadifra.com>
parents: 16504
diff changeset
38 added with :hg:`add X`, even if X would be excluded by a pattern
d8c76c82d012 help: explain effect of .hgignore on tracked files
Adrian Buehlmann <adrian@cadifra.com>
parents: 16504
diff changeset
39 in .hgignore.
d8c76c82d012 help: explain effect of .hgignore on tracked files
Adrian Buehlmann <adrian@cadifra.com>
parents: 16504
diff changeset
40
14044
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
41 Syntax
17267
979b107eaea2 doc: unify section level between help topics
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 17116
diff changeset
42 ======
14044
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
43
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
44 An ignore file is a plain text file consisting of a list of patterns,
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
45 with one pattern per line. Empty lines are skipped. The ``#``
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
46 character is treated as a comment character, and the ``\`` character
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
47 is treated as an escape character.
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
48
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
49 Mercurial supports several pattern syntaxes. The default syntax used
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
50 is Python/Perl-style regular expressions.
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
51
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
52 To change the syntax used, use a line of the following form::
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
53
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
54 syntax: NAME
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
55
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
56 where ``NAME`` is one of the following:
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
57
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
58 ``regexp``
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
59 Regular expression, Python/Perl syntax.
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
60 ``glob``
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
61 Shell-style glob.
41282
4fab8a7d2d72 match: support rooted globs in hgignore
Valentin Gatien-Baron <vgatien-baron@janestreet.com>
parents: 25284
diff changeset
62 ``rootglob``
4fab8a7d2d72 match: support rooted globs in hgignore
Valentin Gatien-Baron <vgatien-baron@janestreet.com>
parents: 25284
diff changeset
63 A variant of ``glob`` that is rooted (see below).
14044
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
64
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
65 The chosen syntax stays in effect when parsing all patterns that
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
66 follow, until another syntax is selected.
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
67
41282
4fab8a7d2d72 match: support rooted globs in hgignore
Valentin Gatien-Baron <vgatien-baron@janestreet.com>
parents: 25284
diff changeset
68 Neither ``glob`` nor regexp patterns are rooted. A glob-syntax
4fab8a7d2d72 match: support rooted globs in hgignore
Valentin Gatien-Baron <vgatien-baron@janestreet.com>
parents: 25284
diff changeset
69 pattern of the form ``*.c`` will match a file ending in ``.c`` in any
4fab8a7d2d72 match: support rooted globs in hgignore
Valentin Gatien-Baron <vgatien-baron@janestreet.com>
parents: 25284
diff changeset
70 directory, and a regexp pattern of the form ``\.c$`` will do the
4fab8a7d2d72 match: support rooted globs in hgignore
Valentin Gatien-Baron <vgatien-baron@janestreet.com>
parents: 25284
diff changeset
71 same. To root a regexp pattern, start it with ``^``. To get the same
4fab8a7d2d72 match: support rooted globs in hgignore
Valentin Gatien-Baron <vgatien-baron@janestreet.com>
parents: 25284
diff changeset
72 effect with glob-syntax, you have to use ``rootglob``.
14044
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
73
25284
7072b91ccd20 help: add documentation on include: and subinclude:
Durham Goode <durham@fb.com>
parents: 20532
diff changeset
74 Subdirectories can have their own .hgignore settings by adding
7072b91ccd20 help: add documentation on include: and subinclude:
Durham Goode <durham@fb.com>
parents: 20532
diff changeset
75 ``subinclude:path/to/subdir/.hgignore`` to the root ``.hgignore``. See
7072b91ccd20 help: add documentation on include: and subinclude:
Durham Goode <durham@fb.com>
parents: 20532
diff changeset
76 :hg:`help patterns` for details on ``subinclude:`` and ``include:``.
7072b91ccd20 help: add documentation on include: and subinclude:
Durham Goode <durham@fb.com>
parents: 20532
diff changeset
77
16504
e3c7ca15cde2 doc: add note about pattern rooted/unrooted cases to "hgignore" and "patterns"
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 14668
diff changeset
78 .. note::
20532
f1a3ae7c15df help: remove last occurrences of ".. note::" without two newlines
Simon Heimberg <simohe@besonet.ch>
parents: 17267
diff changeset
79
16504
e3c7ca15cde2 doc: add note about pattern rooted/unrooted cases to "hgignore" and "patterns"
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 14668
diff changeset
80 Patterns specified in other than ``.hgignore`` are always rooted.
e3c7ca15cde2 doc: add note about pattern rooted/unrooted cases to "hgignore" and "patterns"
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 14668
diff changeset
81 Please see :hg:`help patterns` for details.
e3c7ca15cde2 doc: add note about pattern rooted/unrooted cases to "hgignore" and "patterns"
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 14668
diff changeset
82
14044
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
83 Example
17267
979b107eaea2 doc: unify section level between help topics
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 17116
diff changeset
84 =======
14044
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
85
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
86 Here is an example ignore file. ::
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
87
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
88 # use glob syntax.
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
89 syntax: glob
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
90
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
91 *.elc
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
92 *.pyc
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
93 *~
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
94
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
95 # switch to regexp syntax.
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
96 syntax: regexp
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
97 ^\.pc/
44955
b77d5b568496 ignore: note debugignore on ignore man page
Adam Hull <adam@hmlad.com>
parents: 43632
diff changeset
98
b77d5b568496 ignore: note debugignore on ignore man page
Adam Hull <adam@hmlad.com>
parents: 43632
diff changeset
99 Debugging
b77d5b568496 ignore: note debugignore on ignore man page
Adam Hull <adam@hmlad.com>
parents: 43632
diff changeset
100 =========
b77d5b568496 ignore: note debugignore on ignore man page
Adam Hull <adam@hmlad.com>
parents: 43632
diff changeset
101
b77d5b568496 ignore: note debugignore on ignore man page
Adam Hull <adam@hmlad.com>
parents: 43632
diff changeset
102 Use the ``debugignore`` command to see if and why a file is ignored, or to
b77d5b568496 ignore: note debugignore on ignore man page
Adam Hull <adam@hmlad.com>
parents: 43632
diff changeset
103 see the combined ignore pattern. See :hg:`help debugignore` for details.