Git ignores a file you did not exclude: find the exact rule source
By ON Lab · Sources checked November 8, 2026
Run git check-ignore -v -- "path/to/file" to inspect the rule behind an unexpectedly ignored path. The verbose result identifies its source file, line number, pattern and queried path. The cause may be a nested .gitignore, the repository's local exclude file or a configured excludes file, rather than the top-level .gitignore you already read.
Historical readers asked why images were ignored despite a short visible ignore file, and how to identify one matching rule among many nested files. We checked current Git documentation and tested three rule sources in a disposable repository. We did not read or modify a reader's actual global Git configuration.
Ask about the exact path first
git status --short -- "path/to/file"
git check-ignore -v -- "path/to/file"Use the actual repository and the exact relative path. Quote a path containing spaces. The double hyphen separates options from pathnames. A guessed path or a shell-expanded wildcard may answer a different question from the one file you intended to inspect.
Verbose output uses a source-and-line prefix followed by the pattern and pathname. Read all four parts. Knowing that a path is ignored is less useful than knowing which file supplies the effective rule. A nested file can explain why siblings in another directory behave differently.
Three rule sources we actually tested
Our fixture contained a top-level ignore file, a local repository exclude file and a separate file selected by the repository-local core.excludesFile setting. That last setup tests a configured excludes source without changing any user's global configuration.
| Fixture path | Matching source | Pattern |
|---|---|---|
| asset.tmp | .gitignore | *.tmp |
| asset.local | .git/info/exclude | *.local |
| asset.private | Configured fixture excludes file | *.private |
Each verbose check printed its expected source and rule. A fourth ordinary file produced no matching output and exit status 1. The difference was observed from Git's output, not inferred from whether a file appeared in a file browser.
Git documents several levels of exclusion patterns and their precedence. Per-directory .gitignore rules can apply below their location, while .git/info/exclude is local to the repository. core.excludesFile selects another excludes source; it can be set through configuration at different scopes. Do not assume a configured file must have one hard-coded name or live at the same path on every operating system.
If there is no output
The current check-ignore documentation defines status 0 for at least one ignored path, 1 when none of the supplied paths are ignored, and 128 for a fatal error. Capture the status immediately in your shell or process runner. A nonzero result is not automatically a tool crash.
By default, tracked files are outside the ordinary ignored-file check. If your symptom is a tracked file continuing to appear after adding a rule, this is a different problem. The tracked-file and index guide explains that boundary. Avoid removing files from the index merely to diagnose an unexpectedly excluded untracked file.
The documented --no-index option can examine rules without the usual tracked-file distinction. That helps explain a pattern match, but it does not change what is currently tracked. Similarly, an empty result for a misspelled pathname does not prove the intended file has no matching rule.
Inspect configuration without rewriting it
git config --show-origin --get core.excludesFileThis asks where a configured value came from. A missing explicit value does not by itself establish that no default excludes source applies. Use the verbose path check as the direct evidence for the particular file, then inspect the identified source.
Do not copy a global edit from another person's environment before locating your own matching rule. A shared project's .gitignore and a personal excludes file have different audiences. Changing the wrong one can make a local exception affect teammates or leave the original problem untouched.
Make a narrow correction and repeat the check
- Identify whether the file is intended project content, local generated output or something that should remain untracked.
- Read the matching source and neighboring rules.
- Review a narrow correction at the appropriate scope.
- Rerun the exact check-ignore query and inspect the result.
- Review status and the staged diff before any commit.
Negation patterns and excluded parent directories have documented constraints; adding an exclamation mark is not always enough to re-include a nested file. Read the actual parent rules before adding repeated exceptions. If you choose an explicit forced add for an intended file, recognize that it overrides exclusion for that operation and changes the index; it does not explain or remove the underlying rule.
The fixture was limited to locating rules and reading output. It did not force-add excluded files, rewrite a user's configuration or establish what a real project's sharing policy should be. The useful result is an identified cause and a deliberate, reviewed choice about the file.
Checked November 8, 2026. Three exclusion sources and a nonmatching path were tested locally. Complex nested precedence and the original readers' repositories were not reproduced; current official definitions are linked below.