What is .gitignore? (the list of things git pretends not to see)

What it actually is

.gitignore is a plain-text file, usually sitting at the root of your project, with one pattern per line: node_modules/, .env, .DS_Store, *.log. Git reads it before it does anything else and treats every matching file or folder as if it isn’t there, for the purposes of git add, git status, and commits.

Think of it like the “do not photograph” list you hand out before a family photo shoot. Git is about to take a picture of your whole project folder (that’s what a commit is), and .gitignore is the note you post beforehand telling it which stuff to leave out of frame. It doesn’t erase anything already in the picture. It tells the camera what to skip before it clicks.

Why your AI just did this

The moment your agent runs npm install, it creates a node_modules folder with tens of thousands of files in it. The moment it wires up a database or an API key, it creates a .env file with real secrets in it. A careful agent adds both to .gitignore right after, so a plain git add . doesn’t quietly scoop either one into your repo.

The reasoning is practical, not paranoid. node_modules is entirely rebuildable from package.json by anyone who runs npm install, so committing it bloats the repo with files nobody needs to see. .env holds real credentials, and git history is effectively permanent, once a secret is in there, it stays there even if you later delete the file. Build output folders like dist/, .next/, or build/ get the same treatment: they’re regenerated by running the build, so tracking them creates noise and merge conflicts for zero benefit.

When you’ll run into it

• git status still lists node_modules/ as untracked or modified, even though it’s clearly in .gitignore, usually because it was committed before the rule existed.
• Your agent says something like “I’ve added a .gitignore so we don’t commit the dependencies.”
• You clone a repo, run it, and it’s missing node_modules entirely, that’s expected: you run npm install yourself to regenerate it locally.
• git add . skips a file you actually wanted tracked, worth checking whether a pattern in .gitignore is broader than intended (*.json will hide config files too, not just the ones you meant).
• GitHub offers a “.gitignore template” dropdown when you create a new repo, pick the one matching your stack (Node, Python, etc.) as a starting point.

What to check

• .gitignore exists at the project root before your very first git add. Confirm with cat .gitignore
• It covers node_modules/, .env, and whatever your build output folder is called (dist/, .next/, build/)
• git status doesn’t list anything huge or secret-looking as untracked or staged
• If a file was committed before it got gitignored, run git rm --cached <file> (add -r for a folder), then commit, the ignore rule alone doesn’t remove history
• Personal, machine-specific junk like .DS_Store or .vscode/ can live in a global gitignore on your own computer instead of in every project’s file

Say it like a dev

Instead of: “why does git keep showing my node_modules folder” Say: “is node_modules actually gitignored, or did it get committed before the rule existed?”

Instead of: “make git forget about this file” Say: “git rm —cached it and commit, the gitignore rule alone won’t untrack something already in history”

Instead of: “hide my .env so it’s not in the repo” Say: “confirm .env is gitignored before the first commit, not cleaned up after”