Create a .gitignore on Windows (English)

Table of Contents

Introduction

Creating a .gitignore file on Windows is straightforward for experienced developers, but Windows beginners often stumble over hidden pitfalls. This guide provides safe, reliable methods to create .gitignore files on Windows while avoiding common mistakes.

Key Takeaways:

Windows File Explorer limitations and workarounds
UTF-8 encoding traps (BOM vs. no BOM)
Four reliable creation methods
Platform-specific templates
Global ignore configuration

Why Windows Requires Special Attention

Creating .gitignore on Windows differs from macOS/Linux due to three core issues:

1. Hidden File Extensions

Windows Explorer hides known file extensions by default. When you create a file named .gitignore using Notepad:

What you see: .gitignore
Actual filename: .gitignore.txt
Result: Git won’t recognize this file

Solution: Enable “File name extensions” in Explorer’s View tab, or use command-line tools.

2. UTF-8 BOM Encoding

Notepad saves files as “UTF-8 with BOM” by default. The BOM (Byte Order Mark) can cause issues:

Some Git versions may misread BOM-encoded files
Cross-platform teams may encounter inconsistencies
Best practice: Use UTF-8 without BOM

Solution: Use PowerShell, Git Bash, or modern editors (VS Code) that default to UTF-8 without BOM.

3. Explorer Restrictions on Dot-Files

Windows Explorer blocks creating files that start with a dot and have no extension:

Attempting .gitignore directly in Explorer triggers an error
Workaround: Use .gitignore. (trailing dot) in Explorer
Better solution: Use command-line tools

Safe Creation Methods (4 Options)

Method 1: PowerShell (Recommended)

Basic Creation:

# Create empty .gitignore
New-Item .gitignore -ItemType File -Force

# Create with initial content
Set-Content .gitignore "node_modules/`n*.log`nDist/"

Download from GitHub Templates:

# Node.js template
Invoke-WebRequest https://raw.githubusercontent.com/github/gitignore/main/Node.gitignore -OutFile .gitignore

# Python template
Invoke-WebRequest https://raw.githubusercontent.com/github/gitignore/main/Python.gitignore -OutFile .gitignore

Method 2: CMD (Command Prompt)

REM Create empty .gitignore
type nul > .gitignore

REM Create with initial content
echo node_modules/ > .gitignore
echo *.log >> .gitignore
echo Dist/ >> .gitignore

Note: > overwrites, >> appends.

Method 3: Git Bash (Linux-like Environment)

# Create empty .gitignore
touch .gitignore

# Create with content
cat << 'EOF' > .gitignore
node_modules/
*.log
Dist/
EOF

Method 4: Visual Studio Code

Open your project folder in VS Code
Press Ctrl+N to create a new file
Press Ctrl+S to save, name it .gitignore
VS Code automatically uses UTF-8 without BOM

Common .gitignore Templates

1. Node.js / React / Vue.js

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

# Build output
dist/
build/
.next/
out/

# Environment variables
.env
.env.local
.env.production

# IDE
.vscode/
.idea/

# OS files
.DS_Store
Thumbs.db

2. Python / Django / Flask

# Virtual environment
venv/
env/
ENV/
.venv/

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

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

# Django
*.log
db.sqlite3
media/

# Flask
instance/
.webassets-cache

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

3. PHP / Laravel / WordPress

# Dependencies
vendor/
node_modules/

# Laravel
.env
storage/logs/
storage/framework/cache/
storage/framework/sessions/
storage/framework/views/
bootstrap/cache/

# WordPress
wp-config.php
wp-content/uploads/
wp-content/cache/

# IDE
.vscode/
.idea/
*.sublime-*

4. .NET / ASP.NET Core

# Build results
[Dd]ebug/
[Rr]elease/
x64/
x86/
[Bb]in/
[Oo]bj/

# Visual Studio
.vs/
*.suo
*.user
*.userosscache
*.sln.docstates

# NuGet
*.nupkg
packages/

# ASP.NET
project.lock.json
project.fragment.lock.json
artifacts/

# .NET Core
appsettings.Development.json

5. Java / Spring Boot / Maven

# Build output
target/
build/
out/

# IDE
.idea/
*.iml
.vscode/
.eclipse/
.classpath
.project

# Gradle
.gradle/
gradle/

# Maven
pom.xml.tag
pom.xml.releaseBackup
pom.xml.versionsBackup

# Spring Boot
application-local.yml
application-dev.properties

# OS
.DS_Store
Thumbs.db

6. General IDE / Editor Files

# Visual Studio Code
.vscode/
*.code-workspace

# JetBrains IDEs
.idea/
*.iml
*.iws
*.ipr

# Sublime Text
*.sublime-project
*.sublime-workspace

# Vim
*.swp
*.swo
*~

# Emacs
*~
#*#
.#*

# macOS
.DS_Store
.AppleDouble
.LSOverride

# Windows
Thumbs.db
ehthumbs.db
Desktop.ini
$RECYCLE.BIN/

# Linux
*~
.directory
.Trash-*

Global .gitignore Configuration

Instead of copying OS-specific rules to every project, configure a global ignore file:

Setup Steps

# 1. Create global ignore file
touch ~/.gitignore_global

# 2. Configure Git to use it
git config --global core.excludesfile ~/.gitignore_global

Recommended Global Rules

# Windows
Thumbs.db
ehthumbs.db
Desktop.ini
$RECYCLE.BIN/

# macOS
.DS_Store
.AppleDouble
.LSOverride
._*

# Linux
*~
.directory

# IDEs
.vscode/
.idea/
*.swp
*.swo
*.sublime-*

Verify Configuration

# Check global ignore file path
git config --global core.excludesfile

# View configuration with source
git config --show-origin core.excludesfile

Working with .gitattributes

The .gitattributes file controls line ending normalization, which is crucial for cross-platform teams:

Create .gitattributes

# PowerShell
New-Item .gitattributes -ItemType File -Force

Recommended Rules

# Auto detect text files and normalize line endings to LF in repository
* text=auto

# Force LF for source code
*.js text eol=lf
*.jsx text eol=lf
*.ts text eol=lf
*.tsx text eol=lf
*.json text eol=lf
*.py text eol=lf
*.sh text eol=lf
*.yml text eol=lf
*.yaml text eol=lf

# Force CRLF for Windows scripts
*.bat text eol=crlf
*.cmd text eol=crlf
*.ps1 text eol=crlf

# Binary files (don't modify)
*.png binary
*.jpg binary
*.gif binary
*.ico binary
*.pdf binary
*.zip binary
*.exe binary
*.dll binary

Why This Matters

Windows: Uses CRLF (rn) line endings
macOS/Linux: Uses LF (n) line endings
Without .gitattributes: Git may show false diffs, or files may break on different platforms
With .gitattributes: Git automatically normalizes line endings

Validation and Troubleshooting

Check If a File Is Ignored

# Check specific file
git check-ignore -v node_modules/package.json

# Output example:
# .gitignore:1:node_modules/    node_modules/package.json
#            ↑ line number      ↑ matching rule

Force Add an Ignored File

# Sometimes you need to track a normally-ignored file
git add -f special-config.env

Remove Already-Tracked Files

If you added .gitignore after committing files, they remain tracked:

# Remove from Git index but keep local file
git rm --cached filename

# Remove entire directory
git rm -r --cached node_modules/

# Commit the removal
git commit -m "Remove ignored files from tracking"

Common Issues

Problem	Cause	Solution
Rules not working	Files already tracked	`git rm --cached`
Wrong file created	Hidden extensions	Enable extension visibility
Encoding issues	UTF-8 with BOM	Use PowerShell or VS Code
Global rules ignored	Not configured	`git config --global core.excludesfile`

.gitignore Syntax and Best Practices

Pattern Syntax

# Ignore specific file
config.env

# Ignore all files with extension
*.log

# Ignore directory and contents
node_modules/

# Ignore files in specific directory only
/build/output.txt

# Ignore files recursively
**/temp/

# Negation (don't ignore)
!important.log

# Character range
*.[oa]  # Matches *.o and *.a

Best Practices

Project-level vs. Global:
- Project: Build artifacts, dependencies, environment configs
- Global: IDE files, OS files, personal tools
Organize by Category:

# Dependencies
node_modules/
vendor/

# Build output
dist/
build/

# Environment
.env
.env.local

# IDE
.vscode/
.idea/

# OS
.DS_Store
Thumbs.db

Use Comments: Explain non-obvious rules
Start Specific, Then General: Easier to debug
Commit Early: Add .gitignore before your first commit

Frequently Asked Questions

Q1: Can I create .gitignore using Notepad?

A: Technically yes, but not recommended. You must:

Enable file extension visibility in Explorer
Save as “UTF-8” (not “UTF-8 with BOM”)
Manually verify no .txt extension was added

Recommendation: Use PowerShell, Git Bash, or VS Code for reliability.

Q2: Why isn’t my .gitignore working?

Most common cause: The files are already tracked by Git.

Solution:

git rm --cached filename  # Remove from index
git commit -m "Apply .gitignore rules"

Q3: Should I commit .gitignore?

A: Yes, .gitignore should be committed and shared with your team.

Don’t commit: .git/info/exclude (personal ignore rules only for you)

Q4: How do I ignore files only on my machine?

A: Use .git/info/exclude instead of .gitignore:

# Edit local exclude file
notepad .git/info/exclude

# Add your rules (same syntax as .gitignore)
my-notes.txt
temp/

This won’t affect other team members.

Q5: Where can I find .gitignore templates?

Official GitHub Repository: github/gitignore

Online Generator: gitignore.io

Download via PowerShell:

Invoke-WebRequest https://raw.githubusercontent.com/github/gitignore/main/Node.gitignore -OutFile .gitignore

Summary

Creating .gitignore on Windows requires awareness of platform-specific quirks:

Avoid Notepad: Use PowerShell, Git Bash, or VS Code
Check encoding: UTF-8 without BOM is safest
Verify filenames: Enable extension visibility or use command-line tools
Use templates: Start with GitHub’s official templates
Configure global rules: Keep OS/IDE files out of all projects
Pair with .gitattributes: Normalize line endings for cross-platform teams

Quick Start Command (PowerShell):

# Download Node.js template and start working
Invoke-WebRequest https://raw.githubusercontent.com/github/gitignore/main/Node.gitignore -OutFile .gitignore
git add .gitignore
git commit -m "Add .gitignore"

Following these practices ensures clean Git repositories and prevents accidentally committing sensitive or unnecessary files.