Ignoring Files

What ignoring means

Git has one job during ordinary work: notice which project files have changed so you can stage and commit the intentional ones. Ignore rules tell Git which untracked paths should stay quiet during that process.

The word untracked is the hinge. If Git already tracks a file, adding a matching rule later will not make Git forget it. Ignore rules are a filter for new paths, not an undo button for paths already in the index.

Where ignore rules live

Git reads ignore patterns from several places. Use the location that matches the audience for the rule: the whole team, only this clone, or every repository on your machine.

A repository can have more than one .gitignore. A file in a subdirectory applies to paths under that directory, and deeper rules can override broader ones. In practice, one root .gitignore is enough for many projects; nested files are useful when a subproject has its own build output.

git config --global core.excludesFile ~/.config/git/ignore

Pattern syntax

A .gitignore file is line-oriented. Blank lines are separators. Lines beginning with # are comments. The useful work happens through simple glob-style patterns.

# compiled objects and logs
*.o
*.log

# dependency and build directories
node_modules/
dist/

# a root-only file
/local.sqlite

Directories and depth

Slashes decide where a pattern can match. A trailing slash says "directory only." A leading slash anchors the pattern relative to the directory containing the .gitignore. A slash in the middle makes the pattern relative to that ignore file's directory.

The difference is easiest to see with the same word in three shapes:

Negation and re-including files

A pattern beginning with ! reverses an earlier ignore rule. This is useful when you ignore a broad class of files but intentionally keep one example, fixture, or placeholder.

*.env
!.env.example

The ordering matters: Git uses the last matching rule at the relevant precedence level. Put the broad ignore first, then the exception.

# too broad if you want to keep something inside logs/
# logs/

# ignore contents, then re-include the placeholder
logs/*
!logs/.gitkeep

Tracked files are different

The most common surprise is adding a rule and still seeing the file in git status. That usually means the file is already tracked. Ignore rules do not remove files from history or from the index.

To stop tracking a file while keeping your local copy, remove it from the index with git rm --cached, then commit both the removal-from-tracking and the ignore rule.

git rm --cached app.log
printf "app.log\n" >> .gitignore
git add .gitignore
git commit -m "Stop tracking generated log file"

Use that command carefully. It does not delete your working copy when you pass --cached, but the next person who pulls your commit will see Git remove that tracked file from their checkout unless it is recreated locally. That is usually correct for build output and logs; it is not correct for real source files.

What to ignore

A healthy ignore file is boring. It should describe outputs and local state, not hide uncertainty. If a file is needed to build, test, deploy, or understand the project, think twice before ignoring it.

Good candidates

• Generated build output: dist/, build/, target/, object files, bundles, and compiled classes.
• Dependency caches: folders like node_modules/ when dependencies are restored from a manifest and lockfile.
• Runtime clutter: logs, pid files, coverage output, temporary databases, and local caches.
• Machine-local files: OS metadata, editor backup files, and per-user scratch files.
• Secrets and private env: .env, key files, tokens, local credentials, and generated certificates.

Files that need a policy

Lockfiles, generated documentation, snapshots, schema files, and checked-in assets are project decisions. Some teams commit them because they make builds reproducible; others regenerate them. The ignore file should reflect the policy, not silently decide it.

Checking why a file is ignored

When Git ignores something you expected to stage, ask Git which rule matched. git check-ignore -v prints the source file, line number, pattern, and path.

git check-ignore -v dist/app.js

A typical answer looks like this:

.gitignore:12:dist/	dist/app.js

If the command prints nothing, no ignore pattern matched that untracked path. If the file is tracked and you are debugging why it slipped in earlier, add --no-index to test the ignore rules without consulting the index.

git check-ignore -v --no-index path/to/file

Common pitfalls

Worked examples

node_modules/
dist/
coverage/
*.log
.env
!.env.example

uploads/*
!uploads/.gitkeep

git rm --cached .env
printf ".env\n!.env.example\n" >> .gitignore
git add .gitignore
git commit -m "Ignore local environment file"

git check-ignore -v docs/build/report.pdf

scratch.local