git check-ignore

Tells you which .gitignore rule matched.

🎯 What & why

Tells you which .gitignore rule (and which file, which line) is causing a path to be excluded. The first thing to reach for when 'why won't git add this?' strikes.

🧠 Mental model

It walks the same exclude-matching machinery git itself uses: command-line excludes, per-directory .gitignore, .git/info/exclude, and the global core.excludesFile, in order. First match wins; later patterns can re-include with a leading '!'.

🛠️ Synopsis

git check-ignore [<options>] <pathname>...
git check-ignore [<options>] --stdin

Reports which gitignore pattern (if any) excludes each path. Exit code
encodes the answer: 0 = at least one path is ignored, 1 = none are,
128 = a real error occurred. Quiet/verbose flags change output, not
status.

🎚️ Switches & options

Flag	What it does
`-v, --verbose`	Print source <file>:<line>:<pattern> alongside each path. Use this 95% of the time.
`-n, --non-matching`	Also show paths with no matching rule (with -v, source columns are blank). Lets you batch-classify a list.
`--no-index`	Ignore the index when deciding. Lets you debug rules even if a path is already tracked (tracked files are normally exempt from being 'ignored').
`--stdin`	Read paths from stdin instead of argv. Pair with -z for NUL-delimited input from `find -print0`/`ls-files -z`.
`-z`	NUL-terminate input (with --stdin) and output. Use whenever paths may contain newlines or spaces.
`-q, --quiet`	Suppress output; just set the exit code. Perfect for shell `if` tests. Only one path allowed.

💡 Use cases

Debug 'why isn't my build artifact being added?' — point check-ignore -v at it and read the source line.
Audit a directory of generated files to confirm they are all ignored before a commit.
Pre-flight a script that adds files: skip any path for which check-ignore -q returns 0.
Verify a new pattern in .gitignore actually catches what you intended (and nothing more).

🧪 Examples

Show the rule and source

git check-ignore -v build/output.o

Classify many paths

git ls-files -o -z | git check-ignore -v -n --stdin -z

Test in a script

git check-ignore -q dist/ && echo skipping

Probe a tracked path

git check-ignore -v --no-index docs/notes.md

🎓 Recommendations

Always pass -v. Bare check-ignore prints the path and tells you nothing about why.
Remember tracked files are not reported as ignored even if a pattern matches — use --no-index to see what the pattern would do.
Treat exit code 128 specially in scripts; 0 and 1 are both 'normal' answers.

🪤 Common pitfalls

Negation patterns ('!foo') in a parent directory can't re-include files inside a directory excluded by an earlier rule — check-ignore will correctly still report the directory rule, which surprises people.
Patterns are matched relative to the .gitignore that contains them; copy-pasting a rule from a subdir's file into the root rarely behaves the same.
core.excludesFile and .git/info/exclude are easy to forget; -v will name them when they are the cause.

🔗 Related modules

📝 Quiz

Hit each option, then Check answers. Score is recorded; Next is always open.