Ignoring Files with .gitignore

Not every file in a project folder belongs in Git. Downloaded dependencies such as node_modules can be hundreds of megabytes, log files change every minute, your editor and operating system create junk files, and files like .env hold passwords that must never be shared. A .gitignore file tells Git to pretend these files do not exist.

In this lesson you will write a .gitignore, learn its pattern rules, check why a file is ignored, and fix the common situation where a file was committed before you ignored it.

The problem

Priya's sweet-shop project has grown. It now has npm packages, a log file, a secrets file and some junk files. Look at the status:

git status -s

?? .env
?? Thumbs.db
?? logs/
?? node_modules/
?? notes.tmp

None of these should be committed. With so many untracked files, real changes get lost in the noise, and one careless git add . would publish the database password in .env.

Writing a .gitignore

A .gitignore is a plain text file, usually in the root of the repository, with one pattern per line. Priya creates this one:

# Dependencies installed by npm
node_modules/

# Secrets: never commit these
.env

# Log files, but keep the empty folder
logs/*
!logs/.gitkeep

# Editor and OS junk
*.tmp
Thumbs.db
.DS_Store

Now the status is clean apart from the two files she does want to commit:

git status -s -uall

?? .gitignore
?? logs/.gitkeep

The .gitignore file itself should be committed, so everyone who clones the project gets the same rules:

git add .gitignore logs/.gitkeep
git commit -m "Add .gitignore and keep logs folder"

[main eee3426] Add .gitignore and keep logs folder
 2 files changed, 15 insertions(+)
 create mode 100644 .gitignore
 create mode 100644 logs/.gitkeep

Git does not track empty folders, only files. That is why people put a small placeholder such as .gitkeep inside a folder they want to keep. The name is only a convention; Git gives it no special meaning.

Pattern rules

Two rules trip people up. First, later lines win, so a ! exception must come after the rule it overrides. Second, Git cannot re-include a file if its parent folder is ignored. That is why the example uses logs/* (ignore everything inside logs) instead of logs/ (ignore the folder itself): with logs/, the !logs/.gitkeep line would have no effect.

You can also put a .gitignore inside a subfolder; its patterns then apply relative to that folder.

Why is this file ignored?

When a file is ignored and you do not know why, ask Git. git check-ignore -v prints the file, line number and pattern responsible:

git check-ignore -v .env logs/app.log notes.tmp logs/.gitkeep

.gitignore:5:.env	.env
.gitignore:8:logs/*	logs/app.log
.gitignore:12:*.tmp	notes.tmp
.gitignore:9:!logs/.gitkeep	logs/.gitkeep

The last line shows the ! exception matched, which means logs/.gitkeep is not ignored. To see every ignored file in the project, use git status --ignored -s; ignored entries are marked with !!.

Ignoring a file that is already tracked

.gitignore only affects untracked files. If a file is already committed, Git keeps tracking it no matter what the ignore file says. Priya once committed settings.local.ini, her personal settings. She adds it to .gitignore, changes the file, and Git still reports it:

git status -s

M .gitignore
M settings.local.ini

The fix is to remove the file from the index while keeping it on disk, with --cached:

git rm --cached settings.local.ini
git commit -am "Stop tracking local settings file"

rm 'settings.local.ini'
[main 2c0ebc4] Stop tracking local settings file
 2 files changed, 1 insertion(+), 1 deletion(-)
 delete mode 100644 settings.local.ini

The file is still in Priya's folder, and from now on Git ignores it. Teammates who pull this commit will have the file deleted from their working tree, so warn them to back it up first if it matters.

Global and private ignore rules

Some junk comes from your computer, not the project: Thumbs.db on Windows, .DS_Store on macOS, editor folders such as .idea/. Instead of adding these to every project, put them in a personal ignore file and tell Git about it once:

git config set --global core.excludesFile "~/.gitignore_global"

For rules that apply to only one repository on your machine and should not be shared, add them to .git/info/exclude, which works like .gitignore but is never committed.

You do not have to write .gitignore files from scratch. When you create a repository on GitHub, you can pick a starter template for your language (Node, Python, Java and many more), and GitHub publishes its collection of templates in the github/gitignore repository.

Common mistakes

• Adding a rule after the file was committed and wondering why Git still tracks it. Run git rm --cached <file>.
• Using folder/ with a ! exception inside it. Ignore the contents with folder/* instead.
• Ignoring .gitignore itself. Commit it so the whole team shares the rules.
• Committing .env "just for now". Secrets in history are leaked secrets. Commit an example file such as .env.example with fake values instead.

Key points

• .gitignore lists patterns of untracked files Git should ignore; commit it with the project.
• * matches any characters, a trailing / matches folders only, a leading / anchors to the .gitignore folder, and ! re-includes a file.
• git check-ignore -v <file> explains which rule ignores a file.
• Ignore rules do not affect tracked files; use git rm --cached to stop tracking one.
• Personal rules go in a global excludes file or .git/info/exclude.

.venv/
__pycache__/
*.pyc
/secrets.json
data/*.csv
!data/sample.csv

git check-ignore -v data/march.csv

.gitignore:5:data/*.csv	data/march.csv