Git check-ignore explains how Git’s exclusion rules apply to a path. It is a diagnostic tool for questions such as “Why is this generated file missing from status?” or “Which rule keeps excluding this fixture?” The command can reveal the source file, line number, and matching pattern instead of leaving developers to guess.
Its scope is the exclusion mechanism, not secret protection or filesystem access. A path can be ignored by Git and still be readable, executable, included in a container build, or copied into an archive. Use the result to understand Git behavior, then review other workflows separately.
Start with the symptom and repository context
Confirm the repository and the exact relative path being investigated. A similarly named file in another directory may encounter a different per-directory ignore file. An IDE can also hide files through settings unrelated to Git.
Check whether the path is tracked before assuming an ignore rule is responsible. Git’s ignore mechanism primarily affects untracked paths; an already tracked file does not become untracked merely because a new rule matches its name.
Keep the diagnostic read-only initially. Deleting files, removing them from the index, or rewriting rules before identifying the cause can destroy useful evidence. A small inspection command is usually a better first step than a broad cleanup.
Git check-ignore verbose output identifies provenance
For a controlled path in the current repository, use:
git check-ignore --verbose -- build/report.json
git check-ignore --verbose --non-matching -- build/report.json
git check-ignore --verbose --no-index -- config/local.envThe paths are examples. The first command shows the matching rule’s origin when a match is reported. The second can also emit a record for a path that matches no pattern. The third evaluates the rule without the normal index check, which is useful when investigating a tracked path.
Verbose output can identify rules from repository ignore files, the local .git/info/exclude file, or the configured global exclusion file. This provenance helps explain why one developer sees behavior that another does not.
Do not edit a global ignore configuration simply because its rule appears in one project. Determine whether the desired exception belongs in the project or in the user’s personal workflow.
A negated pattern changes the interpretation
Verbose output is not always proof that a path is excluded. A reported pattern beginning with ! is a negation rule, meaning the matching path is not excluded under that rule’s interpretation.
Read the pattern itself and the overall documented ignore precedence. Rules can interact across directories, and a later exception may not have the effect expected when a parent directory is excluded. Use a controlled fixture to test the actual path rather than mentally simulating a large rule set.
Keep source, line number, pattern, and path together in an explanation. Copying only the pattern loses the information needed to understand where it came from and whether it is the active project rule or a local customization.
Tracked paths require a deliberate distinction
By default, tracked files are not shown because ignore rules do not apply to their tracked status. An empty diagnostic result can therefore mean something different from “no rule would match this name.”
The --no-index option asks the command not to consult the index while undertaking the check. It helps answer the hypothetical rule question for a path that is already tracked. It does not remove the path from the index or change repository history.
If a sensitive file is already committed, changing an ignore rule is not a complete remediation. Rotate exposed credentials, review affected systems, and follow a deliberate history and access cleanup process where necessary. A diagnostic explaining a match cannot erase earlier publication.
Preserve exit-status meaning in automation
The documented statuses distinguish whether one or more paths are ignored, whether none are ignored, and whether a fatal error occurred. Do not convert every nonzero exit into “not ignored.” A repository error and an ordinary no-match result need different handling.
When checking several paths, the overall status is not a per-path classification table. Parse individual records when the application needs an answer for every input. --non-matching with verbose output can make unmatched records explicit.
Quiet mode is intended for a single path. Use it only when a boolean-style check is genuinely enough, and still preserve the fatal-error path. An automation gate should fail visibly when its repository context is wrong rather than approving a file on uncertain evidence.
Use machine-friendly path boundaries
File names can contain spaces and, on some platforms, line breaks. A diagnostic parser that splits on ordinary whitespace can corrupt the very path it is supposed to explain.
For bulk tooling, use the documented NUL-delimited mode and match its input and output protocol carefully. With --stdin and -z, input paths are NUL-separated rather than newline-separated. Verbose output also changes its delimiters under this mode.
Keep output as data rather than executable shell text. A path or pattern should never be passed to eval merely because it came from Git. Bound the number of requested paths and manage subprocess buffers so a long-running streaming checker does not deadlock.
Fix the smallest relevant rule
Once the cause is known, decide which behavior is actually desired. A generated artifact may properly stay ignored. A committed test fixture may need a narrow exception. A personal editor file may belong in local exclusions rather than the shared project policy.
Test the changed rule against neighboring paths. A broad wildcard fix can admit unrelated generated files, while a narrow exception can fail at another directory depth. Keep examples of intended included and excluded paths in a regression suite.
Review the resulting status output before staging changes. Ignore diagnostics explain policy, but staging is a separate action that should still be inspected. Do not assume the corrected rule means every newly visible file should be committed.
Frequently asked questions
Does –no-index untrack a file?
No. It changes the diagnostic check, not repository state. Removing a tracked path from the index is a different operation with different consequences.
Why do two developers get different answers?
They may have different local exclusions, global ignore configuration, repository state, or working directories. Verbose provenance helps identify the difference.
Does an ignored file stay out of every package?
No. Build tools, archives, upload workflows, and container contexts have their own inclusion rules. Test those boundaries independently.
Practical takeaway
Trace the exact path to the exact rule, distinguish tracked state from hypothetical matching, and preserve negation and error semantics. Git check-ignore makes exclusions explainable without confusing them with confidentiality or deployment policy.
Documentation and related reading
Check the official documentation for the exact behavior of your deployed version. For complementary implementation guidance, read the Gitignore rules and secret-removal guide.
