-----------
A `gitignore` file specifies intentionally untracked files that
-git should ignore. Each line in a `gitignore` file specifies a
-pattern.
-
+git should ignore.
+Note that all the `gitignore` files really concern only files
+that are not already tracked by git;
+in order to ignore uncommitted changes in already tracked files,
+please refer to the 'git update-index --assume-unchanged'
+documentation.
+
+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:
-
- * Patterns read from the file specified by the configuration
- variable 'core.excludesfile'.
+order of precedence, from highest to lowest (within one level of
+precedence, the last matching pattern decides the outcome):
- * 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.
+ * 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`.
+
The underlying git plumbing tools, such as
-gitlink:git-ls-files[1] and gitlink:git-read-tree[1], read
+'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],
+tools, such as 'git-status' and 'git-add',
use patterns from the sources specified above.
Patterns have the following format:
- An optional prefix '!' which negates the pattern; any
matching file excluded by a previous pattern will become
- included again.
+ included again. If a negated pattern matches, this will
+ override lower precedence patterns sources.
+
+ - 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
An example:
--------------------------------------------------------------
- $ git-status
+ $ git status
[...]
# Untracked files:
[...]
*.html
# except foo.html which is maintained by hand
!foo.html
- $ git-status
+ $ git status
[...]
# Untracked files:
[...]
GIT
---
-Part of the gitlink:git[7] suite
+Part of the linkgit:git[1] suite