Skip to content
Velloreth
Developer Tools 6 min read

Gitignore Patterns: How to Ignore the Right Files

A .gitignore is a set of patterns, and the rules are subtle. Learn the syntax, the precedence, and the mistakes to avoid.

By

The basics

A .gitignore file lists patterns for paths Git should not track.

node_modules/
dist/
.env
*.log

Each line is a pattern. Blank lines and lines starting with # are ignored.

Pattern syntax

A plain name matches at any depth.

node_modules

This matches node_modules/, src/node_modules/, and packages/app/node_modules/.

A leading slash anchors to the .gitignore’s directory.

/node_modules

This matches only the top-level node_modules/, not a nested one.

A trailing slash matches directories only.

build/

This matches a directory named build but not a file named build.

A wildcard matches within a path segment.

*.log

This matches error.log and debug.log, at any depth.

A double asterisk matches across path segments.

**/logs
logs/**

**/logs matches logs at any depth. logs/** matches everything inside logs.

A question mark matches one character.

file?.txt

Matches file1.txt and fileA.txt.

A character range matches one of a set.

file[0-9].txt

A negation re-includes a path.

*.log
!important.log

The second line re-includes important.log.

Precedence

The rules, in order:

  1. Later patterns override earlier ones. A negation after a broad ignore re-includes the path.
  2. A pattern in a deeper .gitignore overrides one in a parent directory.
  3. A pattern in .git/info/exclude applies to the local repository only.
  4. A global gitignore applies to all repositories, with the lowest precedence.

The order matters. This works:

*.log
!important.log

This does not:

!important.log
*.log

The second line re-ignores the file.

The directory exclusion trap

You cannot re-include a file if its parent directory is excluded.

# Does not work
build/
!build/keep.txt

Git does not descend into an excluded directory, so it never sees the negation. The fix is to exclude the contents rather than the directory.

# Works
build/*
!build/keep.txt

This excludes everything inside build but not build itself, so Git descends and finds the negation.

Ignoring files that are already tracked

Gitignore only affects untracked files. A file that is already tracked stays tracked, and changes to it are still recorded.

Untrack a file but keep it on disk:

git rm --cached file.js

Untrack a directory:

git rm -r --cached node_modules

Then add the pattern to .gitignore and commit.

This is the most common reason a .gitignore “does not work”. The file was committed before the pattern was added.

Debugging

Check whether a file is ignored:

git check-ignore -v file.js
.gitignore:3:*.log	file.log

This prints the matching pattern and the file that contains it, which is the fastest way to find the rule responsible.

List all ignored files:

git status --ignored

List ignored files with their rules:

git ls-files --others --ignored --exclude-standard

What to ignore

Dependencies:

node_modules/
vendor/
.venv/
__pycache__/

Build output:

dist/
build/
out/
*.min.js

Environment and secrets:

.env
.env.local
*.pem
*.key

Logs and caches:

*.log
.cache/
.tmp/

Editor and OS files:

.DS_Store
Thumbs.db
.idea/
.vscode/
*.swp

Test and coverage output:

coverage/
.nyc_output/

Global versus project

Project .gitignore — committed, shared with the team. Build output, dependencies, and project-specific files.

Global gitignore — local, applies to all repositories. Editor and OS files.

git config --global core.excludesfile ~/.gitignore_global
# ~/.gitignore_global
.DS_Store
.idea/
.vscode/
*.swp

The split matters: an editor file is not a property of the project, so it does not belong in the project’s .gitignore. Putting it there adds noise for everyone.

.git/info/exclude — local to one repository, not committed. Useful for a personal file that should not be shared.

Common mistakes

Committing node_modules. Dependencies are reproducible from the lockfile. Committing them bloats the repository and causes constant conflicts.

Committing .env. Secrets should never be in the repository. Ignore .env and commit a .env.example with placeholder values.

Ignoring the lockfile. package-lock.json, yarn.lock, and poetry.lock should be committed, because they pin the exact dependency versions.

A pattern that is too broad. *.json ignores package.json and every config file. Be specific.

Forgetting the trailing slash. build matches a file or directory named build; build/ matches only a directory.

Adding a pattern after the file is tracked. The pattern has no effect until the file is untracked.

Gitignore and the index

The relationship between .gitignore and the index is the source of most confusion.

The index is what matters. Git tracks files in the index. A .gitignore pattern prevents a file from being added to the index, but it does not remove a file that is already there.

git status shows tracked and untracked separately. A modified tracked file appears under “Changes not staged”. An untracked file appears under “Untracked files”, and a matching .gitignore pattern removes it from that list.

git add -f overrides the ignore. A file that matches a pattern can still be added explicitly.

git add -f important.log

This is occasionally useful for a file that is normally ignored but must be committed once.

git check-ignore explains the decision. When a file is unexpectedly ignored or unexpectedly not ignored, this command shows which rule applied.

Gitignore in a monorepo

A monorepo has several projects in one repository, and each may need its own ignore rules.

Nested .gitignore files. A .gitignore in a subdirectory applies to that directory and below, and it overrides the root file for those paths.

# packages/app/.gitignore
dist/
coverage/

The root file handles shared concerns. Dependencies, editor files, and OS files belong in the root.

Be careful with broad patterns. A root pattern like dist/ ignores every dist directory, which is usually what you want. A pattern like build is riskier, because it may match a source directory named build.

Test the rules. git status --ignored shows what is being ignored, which is the fastest way to spot a pattern that is too broad.

Practical guidance

  • Use a leading slash to anchor a pattern to the root.
  • Use a trailing slash to match directories only.
  • Use git check-ignore -v to debug.
  • Untrack files with git rm --cached before ignoring them.
  • Use a global gitignore for editor and OS files.
  • Commit lockfiles, ignore dependencies.
  • Never commit .env — commit .env.example instead.
  • Exclude directory contents (build/*) when you need a negation inside.

For the related guides, see git-stash-guide and git-undo-changes-guide. For the broader context, environment-variables-explained and git-branching-strategies.

Quotable summary

A .gitignore lists patterns for files Git should not track, and the patterns are matched relative to the file’s directory. A leading slash anchors a pattern to the .gitignore’s directory, a trailing slash matches directories only, and a leading exclamation mark negates a pattern. Gitignore does not affect files already tracked, which is the most common reason a pattern appears not to work, so you must untrack them with git rm —cached first. You cannot re-include a file if its parent directory is excluded, so exclude the contents with build/* rather than the directory. Use a global gitignore for editor and OS files and a project gitignore for build output and dependencies, and debug with git check-ignore -v.

Frequently asked questions

Why is my .gitignore not working?
The most common reason is that the file is already tracked. Gitignore only affects untracked files, so you must run git rm --cached to untrack it first. Another reason is a pattern that does not match the path as expected.
What does a leading slash do in a gitignore pattern?
It anchors the pattern to the directory containing the .gitignore. Without a leading slash, the pattern matches at any depth in the tree.
How do I ignore a file everywhere except one directory?
Ignore it broadly, then negate the exception: '*.log' followed by '!important/*.log'. Note that you cannot re-include a file if its parent directory is excluded.
What is a global gitignore?
A gitignore file outside any repository, configured with git config --global core.excludesfile, that applies to all repositories. It is the right place for editor and OS files like .DS_Store and .idea/.
How do I see which rule is ignoring a file?
Use git check-ignore -v <file>, which prints the matching pattern and the file that contains it. This is the fastest way to debug a gitignore.
Should I commit node_modules?
No. Dependencies are reproducible from the lockfile, and committing them bloats the repository. Ignore node_modules and commit the lockfile instead.