How to write a .gitignore file that works
A .gitignore file tells Git which untracked files to leave alone: build output, dependency folders, editor clutter and local secrets. The pattern rules are short but a little subtle. This page explains them and gives starter lists you can trim.
What ignoring does and does not do
Git checks the patterns only for files it is not already tracking. If a file was committed before you added the pattern, Git keeps tracking it. Ignoring also does not delete anything; the file stays on your disk, Git just stops offering it in git status and git add ..
Pattern rules
| Pattern | Matches |
|---|---|
*.log | Any file ending in .log, in any folder |
build/ | A directory called build anywhere (trailing slash means directories only) |
/build/ | Only the build directory at the repository root |
docs/*.pdf | PDFs directly inside docs, not in its subfolders |
docs/**/*.pdf | PDFs at any depth under docs |
!keep.log | Re-include a file that an earlier pattern excluded |
# note | A comment |
\#file | A file name that really starts with # |
The slash rule is the one people trip on. A pattern with a slash at the start or in the middle is anchored to the folder that holds the .gitignore. A pattern with no slash, or only a trailing one, matches at any depth.
Negation has one catch
You cannot re-include a file if its parent folder is excluded, because Git never looks inside an ignored folder. This does not work:
logs/
!logs/.gitkeep
Ignore the contents instead of the folder, then make the exception:
logs/*
!logs/.gitkeep
A starter list for a Node project
# dependencies
node_modules/
# build output
dist/
.next/
coverage/
# environment files with secrets
.env
.env.*
!.env.example
# logs and OS clutter
*.log
.DS_Store
Thumbs.db
A starter list for a Python project
__pycache__/
*.py[cod]
.venv/
venv/
*.egg-info/
.pytest_cache/
.mypy_cache/
dist/
build/
.env
The square brackets in *.py[cod] match one character from the set, so the line covers .pyc, .pyo and .pyd files.
Personal patterns belong elsewhere
Editor files and operating system files such as .idea/, .vscode/ or .DS_Store come from your machine, not from the project. You can list them once in a global ignore file and keep project files focused:
git config --global core.excludesFile ~/.gitignore_global
For a pattern that should apply only to your own clone of one repository, use .git/info/exclude. It works like .gitignore but is never committed.
Fixing a file that is already tracked
- Add the pattern to
.gitignore. - Remove the file from the index but keep it on disk:
git rm --cached config/local.json. For a folder, add-r. - Commit both changes.
If the file held a password or API key, treat that secret as leaked. It is still in the history, so change it at the source.
Debugging a pattern
git check-ignore -v path/to/file prints which .gitignore file and which line caused a match. If it prints nothing, no rule matches. git status --ignored lists everything currently ignored.
Questions
Should package-lock.json be ignored?
Usually not for applications. Lock files record exact dependency versions so every install matches. Commit them.
Can a repository have more than one .gitignore?
Yes. A .gitignore in a subfolder applies to that folder and below, and its patterns are relative to where it sits.
Why are empty folders missing after a clone?
Git tracks files, not folders. Add a placeholder file, often named .gitkeep, if the folder must exist.