mercurial/help/hgignore.txt
author Pierre-Yves David <pierre-yves.david@octobus.net>
Fri, 30 Jun 2017 03:31:35 +0200
changeset 33183 9f95f0bb343b
parent 25284 7072b91ccd20
child 41282 4fab8a7d2d72
permissions -rw-r--r--
configitems: register the 'bundle.reorder' config
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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.
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
    62
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
    63
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
    64
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
    65
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
    66
Neither glob nor regexp patterns are rooted. A glob-syntax pattern of
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
    67
the form ``*.c`` will match a file ending in ``.c`` in any directory,
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
    68
and a regexp pattern of the form ``\.c$`` will do the same. To root a
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
    69
regexp pattern, start it with ``^``.
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
    70
25284
7072b91ccd20 help: add documentation on include: and subinclude:
Durham Goode <durham@fb.com>
parents: 20532
diff changeset
    71
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
    72
``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
    73
: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
    74
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
    75
.. note::
20532
f1a3ae7c15df help: remove last occurrences of ".. note::" without two newlines
Simon Heimberg <simohe@besonet.ch>
parents: 17267
diff changeset
    76
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
    77
  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
    78
  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
    79
14044
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
    80
Example
17267
979b107eaea2 doc: unify section level between help topics
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents: 17116
diff changeset
    81
=======
14044
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
    82
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
    83
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
    84
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
    85
  # use glob syntax.
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
    86
  syntax: glob
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
  *.elc
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
    89
  *.pyc
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
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
    92
  # 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
    93
  syntax: regexp
0528b69f8db4 help: move hgignore man page into built-in help (issue2769)
Yun Lee <yun.lee.bj@gmail.com>
parents:
diff changeset
    94
  ^\.pc/