.gitignore: what to put in it and why

Contents

What is .gitignore

A .gitignore file tells Git which files to ignore — don't track, don't include in commits. Created at the repo root.

What must always be ignored

Dependencies — node_modules, vendor, .venv. Generated automatically by npm install, weighing hundreds of MB, different on every machine.

Environment files — .env. Contains secrets: passwords, API keys, tokens. Commit it once and they're in your public repo (how to pass them into containers safely is in the Docker Compose article).

⚠️ If you already committed .env — just adding it to .gitignore won't help. You need to remove the file from history and rotate all compromised keys.

System files — .DS_Store (macOS), Thumbs.db (Windows).

Build artifacts — dist/, build/, .next/, __pycache__/.

How to organize the branches and commits themselves is covered in Git flow.

Typical .gitignore for Node.js

# Dependencies
node_modules/

# Environment
.env
.env.local
.env.*.local

# Build
dist/
build/
.next/

# Logs
*.log
npm-debug.log*

# System
.DS_Store
Thumbs.db

# Editors
.vscode/settings.json
.idea/

💡 The site gitignore.io generates a ready .gitignore by technology. Type "Node", "Python", "macOS" — you get a full file.

Global .gitignore

System junk is better off in a global gitignore — instead of adding it to every project:

touch ~/.gitignore_global
git config --global core.excludesfile ~/.gitignore_global
echo ".DS_Store" >> ~/.gitignore_global
echo ".idea/" >> ~/.gitignore_global

If a file is already in the repo

Adding it to .gitignore doesn't remove an already-tracked file. To untrack it but keep it locally:

git rm -r --cached node_modules/
git rm --cached .env
git commit -m "remove tracked files from gitignore"

FAQ

What must always go into .gitignore?

Four categories: dependencies (node_modules, vendor, .venv — generated by npm install and weighing hundreds of MB), environment files with secrets (.env, .env.local), build artifacts (dist/, build/, .next/, __pycache__/) and system files (.DS_Store on macOS, Thumbs.db on Windows). Logs (*.log) and editor settings (.idea/, .vscode/settings.json) are worth excluding too.

Why is a file still in the repository even though it is listed in .gitignore?

.gitignore only affects untracked files — Git keeps tracking a file that was already committed. Remove it from the index while keeping it locally: git rm --cached .env or git rm -r --cached node_modules/, then commit. If .env held secrets, that is not enough: they remain in the history, so purge the file from history and rotate every compromised key.

What should I do if I accidentally committed .env with secrets?

Simply adding it to .gitignore will not help — the secrets are already in the commit history, and in a public repo anyone can read them. First rotate all compromised passwords, API keys and tokens, then remove the file from the index with git rm --cached .env and, if needed, scrub it from the repository history.

How do I set up a global .gitignore for all my projects?

Create the file and register it: touch ~/.gitignore_global, then git config --global core.excludesfile ~/.gitignore_global. Put system and editor junk there — .DS_Store, .idea/ — and it will be ignored in every repository without duplicating the rules in each project.

Where can I get a ready-made .gitignore template for my stack?

The gitignore.io site generates a complete file from a list of technologies: type in Node, Python and macOS and you get a full .gitignore. An alternative is GitHub's official template collection, which it also offers when you create a repository.