git-check-ignore

Check whether a file or directory is ignored

$ git check-ignore [path/to/file_or_directory]

$ git check-ignore [path/to/file_or_directory1 path/to/file_or_directory2 ...]

$ git check-ignore --stdin < [path/to/file_list]

$ git check-ignore --no-index [path/to/file_or_directory1 path/to/file_or_directory2 ...]

$ git check-ignore [[-v|--verbose]] [path/to/file_or_directory1 path/to/file_or_directory2 ...]

git check-ignore [] ...
git check-ignore [] --stdin

-q, --quiet
    Do not output ignored paths, just exit with a status of 0 if any path is ignored, or 1 otherwise. This is useful for scripting.

-v, --verbose
    Show details of the matching pattern, including the ignore file, the line number within that file, and the pattern itself. This is the default output format when pathnames are provided as arguments.

-n, --non-matching
    Show non-matching (not-ignored) paths as well. By default, only ignored paths are shown. When combined with --verbose, it will also show patterns that *would* have matched if the path wasn't already tracked (though git-check-ignore doesn't consider tracking status for ignore checks directly).

--stdin
    Read pathnames from standard input, one per line. This is useful for processing a large number of paths.

-z, --null
    With --stdin, pathnames are separated by a NUL character instead of a newline. In verbose output, fields are also separated by NUL characters and paths are terminated by NUL characters. This is useful for parsing the output reliably in scripts.

The git-check-ignore command is a powerful utility designed to help users understand and debug Git's ignore rules. It takes one or more pathnames as arguments and checks whether these paths are ignored by Git, according to the rules defined in .gitignore files, the global excludes file (configured via core.excludesFile), or the .git/info/exclude file.

Unlike git status, which merely lists ignored files, git-check-ignore provides granular detail about *why* a file is ignored. In its default verbose mode, it outputs the path, the specific ignore file containing the matching pattern, the line number within that file, and the exact pattern that caused the ignore. This makes it invaluable for troubleshooting scenarios where files are unexpectedly ignored or not ignored, or for testing new ignore patterns before committing them.

git-check-ignore specifically checks against Git's ignore rules. It does not consider whether a file is already tracked by Git. If a file is tracked in the repository's history, it will never be ignored by .gitignore rules, regardless of any matching patterns. This command will report such a file as 'not ignored' if no pattern matches, but it won't indicate if it's tracked.

The order and specificity of ignore rules are crucial. Rules in a .gitignore file in a subdirectory take precedence over rules in a parent directory. Global exclude files and .git/info/exclude also follow specific precedence rules.

When using the default verbose output (or -v), git-check-ignore produces output for each path that follows this format:

<source_file>:<line_number>:<pattern> <pathname>

For example: .gitignore:5:*.log my_app.log. If a path is not ignored (and -n is used), it will typically show a line like ::my_file.txt (indicating no source file or pattern matched).

Git processes ignore rules in a specific order:
1. Rules in .gitignore files (from the current directory up to the root, with more specific rules taking precedence).
2. Rules in .git/info/exclude.
3. Rules in the global exclude file (specified by core.excludesFile in your Git configuration).
git-check-ignore respects this order when determining which pattern applies to a given path.

The git-check-ignore command was introduced in Git version 1.8.2, released in February 2013. Its addition addressed a long-standing need for a direct and explicit way to debug and verify Git's ignore rules, simplifying the often-complex task of managing and understanding .gitignore files.

gitignore(5), git-status(1), git-ls-files(1), git-config(1)