What is .gitignore? Complete Guide & Troubleshooting

Introduction to .gitignore

A .gitignore file is a text file that tells Git which files or directories to ignore in a project. It's a crucial tool for keeping your repository clean and preventing sensitive or unnecessary files from being tracked.

When you add a file to .gitignore, Git will completely ignore it—it won't be tracked, staged, or committed. This is essential for excluding build artifacts, local configuration files, dependencies, and other files that shouldn't be part of your version control.

✅ Why Use .gitignore?

Keep repository size small
Prevent sensitive data exposure
Avoid conflicts in team projects
Improve build performance
Maintain clean commit history

📁 Common Files to Ignore

Build artifacts (dist/, build/)
Dependencies (node_modules/, vendor/)
Local configs (.env, .env.local)
IDE files (.vscode/, .idea/)
OS files (.DS_Store, Thumbs.db)

How to Use .gitignore

1

Creating a .gitignore File

Create a file named .gitignore in the root of your Git repository:

Terminal Command

touch .gitignore

Or create it directly in your code editor (VS Code, Sublime Text, etc.)

2

Basic Syntax and Patterns

.gitignore uses simple pattern matching. Here are the most common patterns:

Pattern Examples

*.log Ignore all .log files
node_modules/ Ignore entire directory
/.env Ignore .env in root only
**/temp/ Ignore temp dirs anywhere
!important.log Exception: don't ignore
# comment Comments start with #

Pattern Cheatsheet

* - Matches any characters
? - Matches single character
**/ - Matches zero or more directories
/ at start - Root directory
/ at end - Directory only
! - Negation (don't ignore)
[] - Character ranges

3

Common Patterns to Include

Here are common entries for different project types. Click to copy:

Node.js .gitignore

# Dependencies
node_modules/
npm-debug.log*
yarn-debug.log*
yarn-error.log*

# Environment variables
.env
.env.local
.env.*.local

# Build outputs
dist/
build/
*.exe
*.dll

# IDE files
.vscode/
.idea/
*.swp
*.swo

# OS files
.DS_Store
Thumbs.db

PHP .gitignore

# Dependencies
vendor/
composer.lock

# Environment
.env
.env.local

# Cache
storage/framework/cache/*
storage/framework/views/*

# Logs
*.log
storage/logs/*

# IDE
.vscode/
.idea/
.phpstorm.meta.php

Python .gitignore

# Byte-compiled / optimized
__pycache__/
*.py[cod]
*$py.class

# Virtual environments
venv/
env/
ENV/

# Distribution / packaging
dist/
build/
*.egg-info/

# IDE
.vscode/
.idea/

General .gitignore

# OS files
.DS_Store
Thumbs.db
desktop.ini

# IDE
.vscode/
.idea/
*.swp
*.swo

# Logs
*.log

# Temporary files
*.tmp
*.temp

4

Applying .gitignore

After creating or updating .gitignore, you need to apply it:

Important Warning

This command removes all files from cache and re-adds them. Make sure you have no uncommitted changes first!

Apply .gitignore command

git rm -r --cached . && git add . && git commit -m "Apply
                                    .gitignore"

Alternative: Apply to specific files

If you only want to apply .gitignore to specific already-tracked files:

Remove specific file from tracking

git rm --cached filename

Troubleshooting: .gitignore Not Working

If your .gitignore file isn't working as expected, here are common issues and solutions:

1

Files Already Tracked

Git is already tracking files you want to ignore

Solution:

Remove them from Git tracking:

Remove single file

git rm --cached filename

Remove directory

git rm -r --cached directory/

2

Incorrect File Location

.gitignore file is not in the correct location

Solution:

Ensure .gitignore is in the root of your Git repository. Check with:

Find .gitignore files

find . -name ".gitignore" -type f

3

Pattern Syntax Errors

Incorrect pattern syntax in .gitignore

Solution:

Check your patterns:

✅ Correct node_modules/

❌ Incorrect node_modules

✅ Correct *.log

❌ Incorrect .log

4

Case Sensitivity

Case-sensitive file systems causing issues

Solution:

Git is case-sensitive. Ensure your patterns match the exact case:

Example: macOS/Linux

# On macOS/Linux: these are different
.DS_Store
.ds_store

5

Global .gitignore Conflicts

Global .gitignore file overriding local rules

Solution:

Check global gitignore configuration:

Check global config

git config --global core.excludesfile

Common location

~/.gitignore_global

Best Practices

✅ Do

Ignore build artifacts and dependencies - Keep your repo clean of generated files
Ignore local configuration files - Never commit .env or local settings
Use specific patterns over broad ones - *.log is better than *
Comment your .gitignore file - Add context for team members
Test your patterns - Use git check-ignore -v filename
Use global .gitignore for personal files - IDE files, OS files, etc.
Review before committing - Use git status --ignored
Keep it organized - Group related patterns with comments

❌ Don't

Ignore source code files - Only ignore generated/transient files
Commit sensitive data then try to ignore it - Once committed, it's in history
Use overly broad patterns - Avoid * or **/* without good reason
Forget to update .gitignore - Add new dependencies as you add them
Ignore files that should be tracked - Configuration templates should be tracked
Use trailing spaces - They can cause pattern matching issues
Mix OS-specific patterns - Keep Windows, macOS, Linux patterns separate
Ignore without understanding - Know why you're ignoring each pattern

Advanced Tips

📁 Organization Example

Well-organized .gitignore

# ================
# Dependencies
# ================
node_modules/
vendor/
*.jar
*.war

# ================
# Build Outputs
# ================
dist/
build/
*.exe
*.dll

# ================
# Environment
# ================
.env
.env.local
.env.*.local

# ================
# IDE Files
# ================
.vscode/
.idea/
*.swp
*.swo

# ================
# OS Files
# ================
.DS_Store
Thumbs.db
desktop.ini

🔧 Helpful Commands

Check if file is ignored

git check-ignore -v path/to/file

List all ignored files

git ls-files --others --ignored --exclude-standard

Dry run clean

git clean -n

Frequently Asked Questions

Q

Why isn't my .gitignore file working?

The most common reasons are:

The file is already tracked by Git (use git rm --cached filename)
The .gitignore file is not in the root directory
Pattern syntax errors (missing trailing slash for directories)
Case sensitivity issues on macOS/Linux
Global .gitignore file overriding local rules

Check if file is ignored

git check-ignore -v path/to/file

Q

Can I have multiple .gitignore files?

Yes! You can have:

Global .gitignore: Applies to all repositories on your system
Local .gitignore: In the root of your repository
Nested .gitignore files: In subdirectories for specific rules

Set global .gitignore

git config --global core.excludesfile
                                                ~/.gitignore_global

Check global config

git config --global core.excludesfile

Q

How do I remove a file from Git after committing it?

Once a file is committed, it's in your Git history. To remove it:

Important Warning

This rewrites Git history. Don't do this on shared branches!

Remove file from history

git filter-branch --force --index-filter 'git rm --cached
                                            --ignore-unmatch filename' --prune-empty --tag-name-filter cat --
                                            --all

Q

What's the difference between `*.log` and `**/*.log`?

Pattern matching differences:

*.log

Matches files in current directory only
Example: app.log, error.log
Does not match: logs/app.log

**/*.log

Matches files in any directory
Example: logs/app.log, var/log/error.log
Also matches: app.log (current directory)

Q

Should I commit my .gitignore file?

Yes, absolutely! Your .gitignore file should be committed because:

It's part of your project configuration
Team members need the same ignore rules
CI/CD systems need to know what to ignore
It documents what files should be excluded

Best Practice

Commit a .gitignore template and let team members customize their local copies if needed.

Tools and Resources

Helpful Git Commands

git check-ignore -v filename - Check why a file is ignored
git ls-files --others --ignored --exclude-standard - List ignored files
git status --ignored - Show ignored files in status
git clean -n - Show what would be removed (dry run)
git clean -f - Remove untracked files

Introduction to .gitignore

✅ Why Use .gitignore?

📁 Common Files to Ignore

How to Use .gitignore

Creating a .gitignore File

Basic Syntax and Patterns

Pattern Examples

Pattern Cheatsheet

Common Patterns to Include

Applying .gitignore

Important Warning

Alternative: Apply to specific files

Troubleshooting: .gitignore Not Working

Files Already Tracked

Solution:

Incorrect File Location

Solution:

Pattern Syntax Errors

Solution:

Case Sensitivity

Solution:

Global .gitignore Conflicts

Solution:

Best Practices

✅ Do

❌ Don't

Advanced Tips

📁 Organization Example

🔧 Helpful Commands

Frequently Asked Questions

Why isn't my .gitignore file working?

Can I have multiple .gitignore files?

How do I remove a file from Git after committing it?

Important Warning

What's the difference between *.log and **/*.log?

*.log

**/*.log

Should I commit my .gitignore file?

Best Practice

Tools and Resources

Helpful Git Commands

Online Resources

Need a .gitignore Template?

What's the difference between `*.log` and `**/*.log`?