Git Ignore Files and Check Ignore

Basic

Keep intentionally untracked paths out of ordinary staging

Git ignore rules describe paths that are intentionally untracked. An ignore rule affects whether an untracked path is considered by commands such as `git add`; it does not remove a path that is already tracked. This lesson owns ignore patterns and the diagnostic command `git check-ignore`. The previous lesson owns `git rm --cached`, which can remove a path from the index but does not itself create an ignore rule.

Create a repository-level `.gitignore` rule

A `.gitignore` file contains patterns. A simple pattern such as `*.log` matches log files according to Git’s ignore-pattern rules. The ignored file can remain physically present in the working tree while Git excludes it from normal tracking decisions.

git init --initial-branch=main demo-ignore
cd demo-ignore
git config user.name "Foxipa Git Test"
git config user.email "git-test@example.invalid"
printf "*.log\n" > .gitignore
printf "debug\n" > debug.log
printf "source\n" > source.txt
git status --short

printf "*.log\n" > .gitignore
printf "debug\n" > debug.log?git status --short

Ignored does not mean deleted

An ignore rule is not a filesystem deletion command. An ignored file can remain on disk while Git excludes it from ordinary untracked-path reporting.

test -f debug.log
git status --short --untracked-files=all
git add source.txt
git status --short

test -f debug.log?git status --short --untracked-files=all

A tracked file is not made untracked by `.gitignore`

Git’s ignore documentation is explicit: files already tracked by Git are not affected by ignore rules. Adding a matching pattern does not retroactively remove a tracked path from the index. Stopping tracking is a separate operation, such as the `git rm --cached` boundary taught previously.

printf "notes\n" > notes.log
git add notes.log
git commit -m "Track log file"
printf "*.log\n" > .gitignore
git add .gitignore
git status --short
git ls-files --error-unmatch notes.log

git add notes.log .gitignore?git ls-files --error-unmatch notes.log

Use `git check-ignore` to diagnose an ignored path

`git check-ignore` diagnoses the exclude mechanism. Exit status 0 means at least one provided path is ignored; exit status 1 means none of the provided paths is ignored.

git check-ignore debug.log
printf "exit status: $?\n"
git check-ignore source.txt; printf "exit status: $?\n"

git check-ignore debug.log; printf "exit status: %s\n" "$?"?printf "exit status: 0\n"

Use `--verbose` to identify the matching rule

`git check-ignore --verbose <path>` reports the source, line number, pattern, and pathname for a matching exclude rule. This supplies evidence about which rule actually matched.

git check-ignore --verbose debug.log

git check-ignore debug.log?git check-ignore --verbose debug.log

Check multiple paths and non-matches

`git check-ignore` accepts multiple pathnames. By default, only matching paths are printed. With `--verbose --non-matching`, Git can report both matches and non-matches, which is useful when diagnosing a set of paths.

git check-ignore --verbose --non-matching debug.log source.txt

git check-ignore --verbose debug.log source.txt?git check-ignore --verbose --non-matching debug.log source.txt

Tracked-path diagnosis has a deliberate boundary

By default, `git check-ignore` does not report tracked files because tracked files are not subject to ordinary ignore rules. `--no-index` tells the check not to consult the index. It changes the diagnostic lookup; it does not mutate the index.

git check-ignore --verbose --no-index notes.log

git check-ignore --verbose notes.log?git check-ignore --verbose --no-index notes.log

Practice what you learned

Use the dedicated Git code-completion exercise for this lesson.

Official-source boundary

This lesson is grounded only in the official Git project documentation for `gitignore` and `git-check-ignore`. The current official documentation baseline is Git 2.56.0. The live `git-check-ignore` documentation records no changes from Git 2.53.0 through 2.56.0, while the current `gitignore` documentation records no change in 2.56.0; the local verification executable remains Git 2.47.3. Any behavior not verified against the local executable is not presented as locally executed evidence.