How to Write a .gitignore File: Patterns, Templates, and Common Mistakes

A .gitignore file tells Git which files and directories to exclude from version control. Getting it right prevents accidental commits of build artifacts, secrets, and system files. This guide covers the syntax, common patterns, and ready-to-use templates for popular frameworks.

How .gitignore Works

When you run git add or git status, Git checks each file against your .gitignore patterns. If a file matches, Git pretends it doesn't exist — it won't be tracked, staged, or committed.

Create a .gitignore file in the root of your repository. Git reads it automatically — no configuration needed.

Pattern Syntax

Basic Patterns

# Ignore a specific file
secrets.json

# Ignore all files with an extension
*.log
*.tmp

# Ignore a directory (trailing slash)
node_modules/
dist/
build/

# Ignore files in any subdirectory
**/*.pyc

Wildcards and Patterns

Negation: The Exception Rule

Use ! to un-ignore specific files inside an ignored directory or pattern:

# Ignore all log files
*.log

# But keep this one
!important.log

# Ignore build directory
build/

# But keep the README inside it
!build/README.md

Note: You can't un-ignore a file if its parent directory is ignored. To work around this, un-ignore the directory first, then ignore its contents, then un-ignore the specific file.

Templates by Framework

Node.js / JavaScript

node_modules/
dist/
build/
.next/
.nuxt/
coverage/
*.log
.env
.env.local
.env.*.local

Python

__pycache__/
*.py[cod]
*.egg-info/
dist/
build/
.venv/
venv/
.env
*.sqlite3
.pytest_cache/
.mypy_cache/

Go

# Binary
/bin/
*.exe

# Vendor (if not committing deps)
/vendor/

# IDE
.idea/
.vscode/

# OS
.DS_Store
Thumbs.db

Rust

/target/
Cargo.lock  # for libraries only, commit for binaries
*.pdb

Files You Should Always Ignore

Regardless of your stack, these should be in every .gitignore:

Secrets and Environment Files

.env
.env.local
.env.*.local
*.pem
*.key
credentials.json
service-account.json

This is critical. Accidentally committing API keys, database passwords, or private keys is one of the most common security incidents. Even if you delete the file later, it remains in Git history forever.

OS and Editor Files

# macOS
.DS_Store
._*

# Windows
Thumbs.db
Desktop.ini

# Editors
.idea/
.vscode/
*.swp
*.swo
*~

Build Outputs and Dependencies

node_modules/
dist/
build/
out/
coverage/
*.min.js
*.min.css

Common Mistakes

Adding .gitignore After Committing Files

.gitignore only prevents untracked files from being added. If a file is already tracked by Git, adding it to .gitignore won't remove it. You need to untrack it first:

# Remove from Git tracking (keeps local file)
git rm --cached .env

# For directories
git rm -r --cached node_modules/

# Then commit
git commit -m "Remove tracked files that should be ignored"

Ignoring Lock Files

Do not ignore lock files. Files like package-lock.json, yarn.lock, pnpm-lock.yaml, Gemfile.lock, and poetry.lock should be committed. They ensure everyone on your team gets the same dependency versions.

The exception is Cargo.lock for Rust libraries (not binaries), since library consumers resolve their own dependencies.

Global .gitignore

For personal files (editor configs, OS files) that apply to all your repos, use a global gitignore instead of adding them to every project:

# Create a global gitignore
git config --global core.excludesFile ~/.gitignore_global

# Then add your patterns to ~/.gitignore_global
echo ".DS_Store" >> ~/.gitignore_global
echo ".idea/" >> ~/.gitignore_global

This keeps project .gitignore files clean and focused on project-specific patterns.

Debugging: Check If a File Is Ignored

Use git check-ignore to see if and why a file is ignored:

# Check if a file is ignored
git check-ignore -v path/to/file

# Output shows which .gitignore file and line caused the match
# .gitignore:3:*.log    path/to/debug.log

Generate Your .gitignore

Use our .gitignore Generator to create a complete .gitignore file for your tech stack in seconds. Select your languages, frameworks, and editors, and get a ready-to-use file. You can also validate your existing .env files with our .env File Validator to catch exposed secrets before they reach your repo.