pathspec: support :(glob) syntax
[gitweb.git] / Documentation / gitignore.txt
index 1b82fe1969ed1cf965d946178a423771dd3cfe5f..54e334e3af1e790b132da5b6af761326d586ce8a 100644 (file)
@@ -13,12 +13,12 @@ DESCRIPTION
 -----------
 
 A `gitignore` file specifies intentionally untracked files that
-git should ignore.
-Files already tracked by git are not affected; see the NOTES
+Git should ignore.
+Files already tracked by Git are not affected; see the NOTES
 below for details.
 
 Each line in a `gitignore` file specifies a pattern.
-When deciding whether to ignore a path, git normally checks
+When deciding whether to ignore a path, Git normally checks
 `gitignore` patterns from multiple sources, with the following
 order of precedence, from highest to lowest (within one level of
 precedence, the last matching pattern decides the outcome):
@@ -53,17 +53,17 @@ be used.
    the repository but are specific to one user's workflow) should go into
    the `$GIT_DIR/info/exclude` file.
 
- * Patterns which a user wants git to
+ * Patterns which a user wants Git to
    ignore in all situations (e.g., backup or temporary files generated by
    the user's editor of choice) generally go into a file specified by
    `core.excludesfile` in the user's `~/.gitconfig`. Its default value is
    $XDG_CONFIG_HOME/git/ignore. If $XDG_CONFIG_HOME is either not set or
    empty, $HOME/.config/git/ignore is used instead.
 
-The underlying git plumbing tools, such as
+The underlying Git plumbing tools, such as
 'git ls-files' and 'git read-tree', read
 `gitignore` patterns specified by command-line options, or from
-files specified by command-line options.  Higher-level git
+files specified by command-line options.  Higher-level Git
 tools, such as 'git status' and 'git add',
 use patterns from the sources specified above.
 
@@ -89,15 +89,15 @@ PATTERN FORMAT
    a match with a directory.  In other words, `foo/` will match a
    directory `foo` and paths underneath it, but will not match a
    regular file or a symbolic link `foo` (this is consistent
-   with the way how pathspec works in general in git).
+   with the way how pathspec works in general in Git).
 
- - If the pattern does not contain a slash '/', git treats it as
+ - If the pattern does not contain a slash '/', Git treats it as
    a shell glob pattern and checks for a match against the
    pathname relative to the location of the `.gitignore` file
    (relative to the toplevel of the work tree if not from a
    `.gitignore` file).
 
- - Otherwise, git treats the pattern as a shell glob suitable
+ - Otherwise, Git treats the pattern as a shell glob suitable
    for consumption by fnmatch(3) with the FNM_PATHNAME flag:
    wildcards in the pattern will not match a / in the pathname.
    For example, "Documentation/{asterisk}.html" matches
@@ -108,11 +108,30 @@ PATTERN FORMAT
    For example, "/{asterisk}.c" matches "cat-file.c" but not
    "mozilla-sha1/sha1.c".
 
+Two consecutive asterisks ("`**`") in patterns matched against
+full pathname may have special meaning:
+
+ - A leading "`**`" followed by a slash means match in all
+   directories. For example, "`**/foo`" matches file or directory
+   "`foo`" anywhere, the same as pattern "`foo`". "**/foo/bar"
+   matches file or directory "`bar`" anywhere that is directly
+   under directory "`foo`".
+
+ - A trailing "/**" matches everything inside. For example,
+   "abc/**" matches all files inside directory "abc", relative
+   to the location of the `.gitignore` file, with infinite depth.
+
+ - A slash followed by two consecutive asterisks then a slash
+   matches zero or more directories. For example, "`a/**/b`"
+   matches "`a/b`", "`a/x/b`", "`a/x/y/b`" and so on.
+
+ - Other consecutive asterisks are considered invalid.
+
 NOTES
 -----
 
 The purpose of gitignore files is to ensure that certain files
-not tracked by git remain untracked.
+not tracked by Git remain untracked.
 
 To ignore uncommitted changes in a file that is already tracked,
 use 'git update-index {litdd}assume-unchanged'.
@@ -160,13 +179,15 @@ Another example:
     $ echo '!/vmlinux*' >arch/foo/kernel/.gitignore
 --------------------------------------------------------------
 
-The second .gitignore prevents git from ignoring
+The second .gitignore prevents Git from ignoring
 `arch/foo/kernel/vmlinux.lds.S`.
 
 SEE ALSO
 --------
-linkgit:git-rm[1], linkgit:git-update-index[1],
-linkgit:gitrepository-layout[5]
+linkgit:git-rm[1],
+linkgit:git-update-index[1],
+linkgit:gitrepository-layout[5],
+linkgit:git-check-ignore[1]
 
 GIT
 ---