diff options
Diffstat (limited to 'Documentation/gitignore.txt')
| -rw-r--r-- | Documentation/gitignore.txt | 164 |
1 files changed, 128 insertions, 36 deletions
diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt index ea79d74b88..473623d631 100644 --- a/Documentation/gitignore.txt +++ b/Documentation/gitignore.txt @@ -7,67 +7,145 @@ gitignore - Specifies intentionally untracked files to ignore SYNOPSIS -------- -$GIT_DIR/info/exclude, .gitignore +$HOME/.config/git/ignore, $GIT_DIR/info/exclude, .gitignore DESCRIPTION ----------- A `gitignore` file specifies intentionally untracked files that -git should ignore. Each line in a `gitignore` file specifies a -pattern. +Git should ignore. +Files already tracked by Git are not affected; see the NOTES +below for details. -When deciding whether to ignore a path, git normally checks +Each line in a `gitignore` file specifies a pattern. +When deciding whether to ignore a path, Git normally checks `gitignore` patterns from multiple sources, with the following -order of precedence: +order of precedence, from highest to lowest (within one level of +precedence, the last matching pattern decides the outcome): - * Patterns read from the file specified by the configuration - variable 'core.excludesfile'. - - * Patterns read from `$GIT_DIR/info/exclude`. + * Patterns read from the command line for those commands that support + them. * Patterns read from a `.gitignore` file in the same directory - as the path, or in any parent directory, ordered from the - deepest such file to a file in the root of the repository. + as the path, or in any parent directory, with patterns in the + higher level files (up to the toplevel of the work tree) being overridden + by those in lower level files down to the directory containing the file. These patterns match relative to the location of the `.gitignore` file. A project normally includes such `.gitignore` files in its repository, containing patterns for files generated as part of the project build. -The underlying git plumbing tools, such as -gitlink:git-ls-files[1] and gitlink:git-read-tree[1], read + * Patterns read from `$GIT_DIR/info/exclude`. + + * Patterns read from the file specified by the configuration + variable 'core.excludesFile'. + +Which file to place a pattern in depends on how the pattern is meant to +be used. + + * Patterns which should be version-controlled and distributed to + other repositories via clone (i.e., files that all developers will want + to ignore) should go into a `.gitignore` file. + + * Patterns which are + specific to a particular repository but which do not need to be shared + with other related repositories (e.g., auxiliary files that live inside + 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 + 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 +'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 -tools, such as gitlink:git-status[1] and gitlink:git-add[1], +files specified by command-line options. Higher-level Git +tools, such as 'git status' and 'git add', use patterns from the sources specified above. -Patterns have the following format: +PATTERN FORMAT +-------------- - A blank line matches no files, so it can serve as a separator for readability. - A line starting with # serves as a comment. + Put a backslash ("`\`") in front of the first hash for patterns + that begin with a hash. - - An optional prefix '!' which negates the pattern; any - matching file excluded by a previous pattern will become - included again. + - Trailing spaces are ignored unless they are quoted with backslash + ("`\`"). - - If the pattern does not contain a slash '/', git treats it as + - An optional prefix "`!`" which negates the pattern; any + matching file excluded by a previous pattern will become + included again. It is not possible to re-include a file if a parent + directory of that file is excluded. Git doesn't list excluded + directories for performance reasons, so any patterns on contained + files have no effect, no matter where they are defined. + Put a backslash ("`\`") in front of the first "`!`" for patterns + that begin with a literal "`!`", for example, "`\!important!.txt`". + + - If the pattern ends with a slash, it is removed for the + purpose of the following description, but it would only find + 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). + + - If the pattern does not contain a slash '/', Git treats it as a shell glob pattern and checks for a match against the - pathname without leading directories. + 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/\*.html" matches - "Documentation/git.html" but not - "Documentation/ppc/ppc.html". A leading slash matches the - beginning of the pathname; for example, "/*.c" matches - "cat-file.c" but not "mozilla-sha1/sha1.c". + For example, "Documentation/{asterisk}.html" matches + "Documentation/git.html" but not "Documentation/ppc/ppc.html" + or "tools/perf/Documentation/perf.html". + + - A leading slash matches the beginning of the pathname. + 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. -An example: + - 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. + +To stop tracking a file that is currently tracked, use +'git rm --cached'. + +EXAMPLES +-------- -------------------------------------------------------------- - $ git-status + $ git status [...] # Untracked files: [...] @@ -85,7 +163,7 @@ An example: *.html # except foo.html which is maintained by hand !foo.html - $ git-status + $ git status [...] # Untracked files: [...] @@ -103,14 +181,28 @@ 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`. -Documentation -------------- -Documentation by David Greaves, Junio C Hamano, Josh Triplett, -Frank Lichtenheld, and the git-list <git@vger.kernel.org>. +Example to exclude everything except a specific directory `foo/bar` +(note the `/*` - without the slash, the wildcard would also exclude +everything within `foo/bar`): + +-------------------------------------------------------------- + $ cat .gitignore + # exclude everything except directory foo/bar + /* + !/foo + /foo/* + !/foo/bar +-------------------------------------------------------------- + +SEE ALSO +-------- +linkgit:git-rm[1], +linkgit:gitrepository-layout[5], +linkgit:git-check-ignore[1] GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[1] suite |