SpunkArt
Command line and project setup

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

PatternMatches
*.logAny 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/*.pdfPDFs directly inside docs, not in its subfolders
docs/**/*.pdfPDFs at any depth under docs
!keep.logRe-include a file that an earlier pattern excluded
# noteA comment
\#fileA 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

  1. Add the pattern to .gitignore.
  2. Remove the file from the index but keep it on disk: git rm --cached config/local.json. For a folder, add -r.
  3. 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.