Skip to content

Understanding .gitignore ​

You have files Git should not track. Compiled binaries, dependency folders, environment secrets, editor temp files. .gitignore tells Git which files to ignore so they never show up in git status, never get staged, and never end up in a commit.

What is .gitignore ​

A plain text file named exactly .gitignore in your repository. Each line is a pattern. Files matching the pattern are ignored.

# This is a comment
node_modules/
.env
*.log

Git reads .gitignore before every status check. If a file matches any pattern, Git pretends it does not exist.

Where .gitignore files live ​

You can have more than one:

LocationScopeWhen to use
Repository root .gitignoreEveryone who clones the repoBuild artifacts, dependencies, compiled output
Subdirectory .gitignoreThat directory and its childrenLanguage-specific ignores in a monorepo
.git/info/excludeOnly you, not committedPersonal scratch files, local config overrides
Global ~/.gitignoreEvery repo on your machineOS files, editor swap files, IDE metadata

Pattern syntax ​

Wildcards ​

# All .log files anywhere in the repo
*.log

# All files in any 'build' directory
build/

# Single-character wildcard: matches file.s, file.c, file.o but not file.xyz
file.?

Comments and blank lines ​

Lines starting with # are comments. Blank lines make long files easier to read.

# Dependencies
node_modules/
vendor/

# Build output
dist/
build/

Negation ​

A line starting with ! un-ignores a file that was previously ignored.

# Ignore all .env files
.env

# But keep the template
!.env.example

Directory separator ​

A trailing / matches only directories. A leading / anchors the pattern to the repository root.

# Ignores only /build at root, not src/build
/build

# Ignores all build directories anywhere
build/

Recursive wildcard ​

** matches zero or more directories.

# All .log files in any directory
**/*.log

# All files inside any 'temp' directory
**/temp/*

Common .gitignore patterns by language ​

Language/FrameworkTypical ignores
Node.jsnode_modules/, npm-debug.log*, .env
Python__pycache__/, *.pyc, .venv/, dist/
Rusttarget/, Cargo.lock (for libraries)
Java*.class, target/, .gradle/, build/
Gobin/, vendor/ (for modules)
C/C++*.o, *.so, *.a, build/

GitHub maintains a library of .gitignore templates at github.com/github/gitignore.

Setting up a global .gitignore ​

Some files no repo should ever track. Set these once for every repo on your machine:

bash
git config --global core.excludesFile ~/.gitignore

Then create ~/.gitignore:

# Editor swap files
*.swp
*.swo
*~

# macOS
.DS_Store

# Windows
Thumbs.db

# IDE
.idea/
.vscode/

Checking why a file is ignored ​

If a file is missing from git status and you are not sure why:

bash
git check-ignore -v config/local.env

Output:

.gitignore:3:*.env  config/local.env

This tells you the exact .gitignore file, line number, and pattern that caused the ignore. No guessing.

What's happening here ​

When you run git status, Git walks every file in your working directory. For each file it checks:

  1. Is it tracked (already in the index)? If yes, show it.
  2. Is it ignored by a .gitignore pattern? If yes, skip it.
  3. Is it in .git/info/exclude? If yes, skip it.
  4. Otherwise, show it as untracked.

The check respects the closest .gitignore in the directory tree. Patterns in a child .gitignore override patterns in a parent .gitignore. The last matching pattern wins.

Common mistakes ​

MistakeWhat happensFix
Adding .gitignore after tracking the filesThe files stay tracked. .gitignore only affects untracked files.git rm --cached <file> to untrack without deleting
Ignoring a directory without trailing /Matches both files and directories named thatAdd trailing / for directory-only ignore
Forgetting negation orderA later *.log overrides an earlier !important.log if patterns conflictNegations must come after the broader pattern they override
Using absolute paths.gitignore patterns are relative to the .gitignore file's locationUse dir/ not /home/user/project/dir/
Committing secrets then adding to .gitignoreThe secret is already in historyUse git filter-repo or git rm --cached and rotate the secret

Pitfalls ​

  • Ignored files are not protected. Anyone who knows the path can still git add -f to force-track an ignored file. .gitignore is a convenience, not a security control.
  • Ignored directories are not searched. If you ignore node_modules/, Git never looks inside it. This improves performance on large dependency trees.
  • Patterns are not shell globs. * matches everything except /. Use ** to cross directory boundaries.
  • Empty directories are never tracked. Git tracks files, not directories. If you ignore every file inside a directory, the directory itself does not appear in the repo.

Quick reference ​

CommandWhat it does
git check-ignore -v <file>Show which .gitignore rule ignored a file
git add -f <file>Force-add an ignored file
git ls-files --ignored --exclude-standardList all currently ignored tracked files
git status --ignoredShow both tracked and ignored files

Git Master — Git Reference for Every Skill Level