mercurial/helptext/hgignore.txt
author Jordi Gutiérrez Hermoso <jordigh@octave.org>
Fri, 15 Nov 2019 15:58:56 -0500
changeset 43718 d155bf11cf22
parent 43632 2e017696181f
child 44955 b77d5b568496
permissions -rw-r--r--
hgweb: add diffs to the json changeset template While it's possible to get the diff for each file individually via an obscure url that I'm not even sure is documented, (e.g. diff/{rev}/{filename}?style=json ), it is more convenient to provide the full diff from the changeset view. This is already normally computed for other non-JSON templates, so it seems like an oversight to omit it for the JSON one. The output format is a bit unwieldy but it's consistent with the existing format output by the aforementioned obscure url.
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.
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/