.gitignore — The Missing File That Exposed Production Secrets

The most common Git mistake is committing something sensitive — API keys, database passwords, .env files, or large binary files. .gitignore is the first line of defense. But it's often added reactively, after the damage is done. A single commit with a .env file means the secrets are in the repository history forever, even if you delete the file in a later commit. This guide covers gitignore patterns, the global gitignore, and the incident where a missing .env entry exposed production API keys within hours of the commit.

Why .gitignore Matters

Every developer has accidentally committed secrets, build artifacts, or large binary files. A .gitignore file tells Git which files to ignore, preventing sensitive data and repository bloat. Without it, you risk exposing API keys, database credentials, or configuration files. Production teams enforce .gitignore to maintain clean, secure repositories. This section explains the consequences of ignoring .gitignore: leaked secrets on public repos, bloated clone times, and merge conflicts from generated files. A well-crafted .gitignore is your first line of defense against these issues.

#!/bin/bash
# Simulate accidental secret commit
echo "API_KEY=sk-12345" > .env
git add .env
git commit -m "Add config"
git push origin main
# Now secret is in history forever unless purged

Anatomy of a .gitignore File

A .gitignore file uses glob patterns to match files and directories. Lines starting with # are comments. Patterns can be absolute (starting with /) or relative. Use to match any string, ? for a single character, and [abc] for character sets. Negate patterns with ! to re-include files. Directories are matched by appending /. For example, /build/ ignores the build directory at the root, while .log ignores all log files. Understanding these patterns is crucial to avoid accidentally ignoring important files or missing dangerous ones.

# Ignore all .env files
.env

# Ignore build output
/build/

# Ignore all log files
*.log

# But keep important.log (negation)
!important.log

# Ignore files in any directory named 'temp'
temp/

Setting Up .gitignore for Different Languages and Frameworks

Different projects have different artifacts. Python projects ignore __pycache__, *.pyc, and virtual environments. Node.js ignores node_modules and package-lock.json (though some teams track lockfiles). Java projects ignore .class files and target/ directories. Use language-specific templates from GitHub's gitignore repository. Never blindly copy-paste; understand each pattern. For example, ignoring .env is universal, but ignoring .vscode/ might be team-specific. Tailor your .gitignore to your exact build process.

# Python
__pycache__/
*.py[cod]
*.so
.Python
env/
venv/

# Node
node_modules/
npm-debug.log*

# Java
*.class
*.jar
*.war
*.nar
target/

# IDE
.idea/
.vscode/
*.swp
*.swo

Global .gitignore for Personal Preferences

Sometimes you want to ignore files globally across all repos, like editor backups or OS files. Use a global .gitignore file configured via git config --global core.excludesFile. This keeps your repo-specific .gitignore clean. Common global ignores: .DS_Store (macOS), Thumbs.db (Windows), *.swp (vim), and .idea/ (JetBrains). However, be cautious: global ignores apply to all repos on your machine, so don't add project-specific patterns there.

#!/bin/bash
# Create global gitignore
echo ".DS_Store" >> ~/.gitignore_global
echo "Thumbs.db" >> ~/.gitignore_global
echo "*.swp" >> ~/.gitignore_global
# Configure git to use it
git config --global core.excludesFile ~/.gitignore_global

Ignoring Secrets: .env, Credentials, and Config Files

Secrets like API keys, database passwords, and tokens must never be committed. The most common pattern is to ignore .env files. But also ignore files like config/secrets.yml, *.pem, or any file containing credentials. Use .env.example as a template committed to the repo. For production, use secret management tools like Vault or AWS Secrets Manager. Never hardcode secrets in code. If a secret is committed, rotate it immediately and purge it from history.

# Secrets
.env
.env.local
.env.*.local

# Config files with secrets
config/database.yml
config/secrets.yml

# SSH keys
*.pem
*.key

# Service account JSONs
*-service-account.json

Ignoring Build Artifacts and Dependencies

Build artifacts like compiled binaries, minified files, and dependency directories bloat your repo. Ignore node_modules/, vendor/, __pycache__/, and build output directories like dist/ or build/. These can be regenerated from source. Ignoring them keeps your repo small and diffs meaningful. However, some teams track lockfiles (package-lock.json, Gemfile.lock) for deterministic builds. Decide as a team what to track.

# Dependencies
node_modules/
vendor/

# Build output
dist/
build/
*.bundle

# Compiled files
*.pyc
*.class
*.o

# Logs
*.log
npm-debug.log*

Handling Nested .gitignore Files

You can have multiple .gitignore files in subdirectories. Patterns in a child .gitignore override parent patterns. This is useful for monorepos where different subprojects have different ignore rules. For example, a frontend directory might ignore node_modules, while a backend directory ignores vendor. However, too many nested files can become confusing. Prefer a single root .gitignore unless you have a clear need for per-directory rules.

# Override root ignore for this directory
!important.log

# Additional ignores for frontend
node_modules/
.next/

Testing Your .gitignore with git check-ignore

Before committing, verify that your .gitignore works as expected. Use git check-ignore -v <file> to see if a file is ignored and which pattern matches. Also use git status to check for untracked files. For CI, add a step to ensure no secrets are staged. Tools like git-secrets or truffleHog can scan for secrets. Never assume your .gitignore is correct; test it.

#!/bin/bash
# Check if .env is ignored
git check-ignore -v .env
# Output: .gitignore:2:.env	.env

# List all ignored files
git ls-files --others --ignored --exclude-standard

Removing Files Already Tracked by Git

If you added a file to .gitignore after it was already tracked, Git still tracks it. You must remove it from the index with git rm --cached <file>. This keeps the file locally but stops tracking changes. For directories, use git rm -r --cached. Then commit the removal. This is common when retrofitting .gitignore to an existing project. Be careful: this will delete the file from other developers' working copies on pull.

#!/bin/bash
# Remove .env from tracking but keep locally
git rm --cached .env
# Commit the removal
git commit -m "Stop tracking .env file"
# Push to remote
git push origin main

Best Practices for Team .gitignore Management

Establish team conventions: commit .gitignore early, review changes in PRs, and use a standard template. Avoid ignoring files that are essential for building (like lockfiles). Document why certain patterns are ignored. Use .gitkeep files to track empty directories. For monorepos, consider a root .gitignore with per-project overrides. Regularly audit your .gitignore to remove stale patterns. Treat .gitignore as code: version it, review it, and test it.

# Team .gitignore conventions
# Do NOT ignore lockfiles
# package-lock.json is tracked

# Ignore all .env files except .env.example
.env
.env.*
!.env.example

# Ignore IDE files
.idea/
.vscode/

# Ignore OS files
.DS_Store
Thumbs.db

Advanced: .gitignore Patterns for Monorepos and CI

In monorepos, use patterns like !/project-a/node_modules to unignore specific directories. For CI, ensure your .gitignore doesn't ignore files needed for build (like lockfiles). Use .gitignore per environment? Not recommended; instead, use environment variables. For CI artifacts, consider a separate .gitignore in the CI workspace. Also, be aware of .gitignore in submodules: each submodule has its own .gitignore.

# Monorepo: ignore all node_modules except project-a
node_modules/
!/project-a/node_modules

# CI: ignore temporary files
*.tmp
*.swp

Recovering from .gitignore Mistakes

Mistakes happen: you accidentally ignored a needed file or committed a secret. To recover, first fix the .gitignore. If a file is ignored but should be tracked, remove the pattern and use git add -f to force add. If a secret is committed, rotate it and use git filter-repo to purge it from history. For large files accidentally committed, use BFG Repo-Cleaner. Always communicate with your team before destructive history rewrites.

#!/bin/bash
# Force add a file that is ignored
git add -f important.config

# Remove a file from history (use with caution)
git filter-repo --path .env --invert-paths

# Then force push
git push origin --force --all