Appearance
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
*.logGit 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:
| Location | Scope | When to use |
|---|---|---|
Repository root .gitignore | Everyone who clones the repo | Build artifacts, dependencies, compiled output |
Subdirectory .gitignore | That directory and its children | Language-specific ignores in a monorepo |
.git/info/exclude | Only you, not committed | Personal scratch files, local config overrides |
Global ~/.gitignore | Every repo on your machine | OS 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.exampleDirectory 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/Framework | Typical ignores |
|---|---|
| Node.js | node_modules/, npm-debug.log*, .env |
| Python | __pycache__/, *.pyc, .venv/, dist/ |
| Rust | target/, Cargo.lock (for libraries) |
| Java | *.class, target/, .gradle/, build/ |
| Go | bin/, 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 ~/.gitignoreThen 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.envOutput:
.gitignore:3:*.env config/local.envThis 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:
- Is it tracked (already in the index)? If yes, show it.
- Is it ignored by a
.gitignorepattern? If yes, skip it. - Is it in
.git/info/exclude? If yes, skip it. - 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
| Mistake | What happens | Fix |
|---|---|---|
Adding .gitignore after tracking the files | The 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 that | Add trailing / for directory-only ignore |
| Forgetting negation order | A later *.log overrides an earlier !important.log if patterns conflict | Negations must come after the broader pattern they override |
| Using absolute paths | .gitignore patterns are relative to the .gitignore file's location | Use dir/ not /home/user/project/dir/ |
Committing secrets then adding to .gitignore | The secret is already in history | Use 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 -fto force-track an ignored file..gitignoreis 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
| Command | What 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-standard | List all currently ignored tracked files |
git status --ignored | Show both tracked and ignored files |