.gitignore

Why this matters

git add . is convenient and dangerous: it stages every untracked file, including the 200 MB of installed packages, the editor's settings folder, the file with your API key. .gitignore is the list of things Git must never offer for staging. A good one makes git status quiet and honest; a missing one is how secrets and junk enter history.

What to ignore

Never ignore: source, tests, documentation, data the project needs, manifests, lock files, the pipeline definition, .gitignore itself.

The file

.gitignore is a plain text file at the root of the repository (extra ones can sit in subfolders). One pattern per line; # starts a comment. The playground's:

# Python
__pycache__/
*.pyc
.venv/

# Secrets and local settings — never commit these
.env
*.local

# Editors and operating systems
.DS_Store
Thumbs.db
.idea/
.vscode/

The six pattern shapes that cover almost every case:

Patterns apply to untracked files only; a file already in history is unaffected (see the trap below).

Templates

Every language has a standard list. GitLab and GitHub both offer templates when creating a project (.gitignore template dropdown), and github.com/github/gitignore is the shared source: Python.gitignore, Node.gitignore and so on. Start from the template for your language and add the secrets and editor lines.

Check whether a file is ignored

$ git check-ignore -v .env src/__pycache__/trailguide.cpython-313.pyc

.gitignore:7:.env	.env
.gitignore:2:__pycache__/	src/__pycache__/trailguide.cpython-313.pyc

Each line names the file, the line number and the pattern that matched. No output means "not ignored". git status --ignored lists all ignored files at the end of the status:

$ git status --ignored

Ignored files:
  (use "git add -f <file>..." to include in what will be committed)
	.env
	src/__pycache__/

nothing to commit, working tree clean

And if you try to add an ignored file, Git refuses and tells you why:

$ git add .env

The following paths are ignored by one of your .gitignore files:
.env
hint: Use -f if you really want to add them.
hint: Disable this message with "git config set advice.addIgnoredFile false"

Take that refusal as a gift. -f exists for the rare legitimate case; a secret is never one.

The trap: already tracked

Ignore rules do not apply to files Git already tracks. If todo.txt was committed and you then add it to .gitignore, it keeps showing as modified. Untrack it once, keeping the file on disk:

$ git rm --cached todo.txt

rm 'todo.txt'

$ git status -s

 M .gitignore
D  todo.txt

Commit both: the file is removed from history going forward, stays on your disk, and the pattern keeps it out from now on. (The file remains in old commits; for secrets that is not enough — lesson 8.7.)

A global ignore for your own noise

Editor folders and .DS_Store are about your machine, not the project. Keep them in a personal, global ignore file so that every repository ignores them, even ones whose .gitignore forgot:

$ git config --global core.excludesFile ~/.gitignore_global
$ printf '.DS_Store\nThumbs.db\n.idea/\n.vscode/\n*.swp\n' > ~/.gitignore_global

Project-specific ignores still belong in the project's .gitignore, so colleagues get them too.

In the tools

Common mistakes

• Ignoring after committing. Untrack with git rm --cached once.
• Ignoring too much. A pattern like *.md in a docs project hides the documentation. Test with git check-ignore -v.
• Putting personal editor folders into the project's .gitignore and nothing else. Fine, but the global ignore file protects you everywhere.
• Committing .env "just for now". Git remembers forever. Use .env.example.