.dockerignore
Home .dockerignore vs .gitignore
SWA Cloud Sponsor Star

.dockerignore vs .gitignore: The Complete Developer's Guide

Master the critical differences between .dockerignore and .gitignore to optimize your development workflow

⚡ Quick Answer: .dockerignore vs .gitignore

The .gitignore file tells Git which files to exclude from version control, while the .dockerignore file tells Docker which files to exclude when building images. Though similar in concept, they have different syntax rules, operate at different stages of development, and serve distinct purposes.

Different syntax rules Different use cases Both critical for security

📚 Complete Guide Contents

Understanding .dockerignore vs .gitignore

Before diving into the differences, let's understand what each file actually does in your development workflow.

.gitignore

Purpose: Controls what Git tracks in version control

Activates: During git add, git status, git commit

Location: Project root (can be nested in subdirectories)

Scope: Local development and remote repositories

Need .gitignore templates? Check out gitignores.com for pre-built patterns for any language or framework.

.dockerignore

Purpose: Optimizes Docker builds by excluding files

Activates: During docker build context creation

Location: Build context root only (no nesting)

Scope: Docker images and build performance

Reduces image size and build time by preventing unnecessary files from reaching Docker daemon.

💡 Critical Insight: Why the Confusion?

Many developers assume .dockerignore vs .gitignore work the same way because both use pattern matching. However, they have fundamentally different pattern matching rules, which is the #1 source of bugs when transitioning between them.

8 Key Differences: .dockerignore vs .gitignore

Here's a comprehensive comparison of how .dockerignore and .gitignore differ in behavior and usage.

Feature .gitignore .dockerignore
Primary Purpose Version control exclusion Build context exclusion
When Activated During git operations (add, commit, status) During docker build command
File Location Project root or any subdirectory Build context root only
Multiple Files Supported ✅ Yes (global, per-directory, nested) ❌ No (single file only)
Default Pattern Depth Matches at any depth by default Matches at root only (requires **/ for depth)
Leading Slash Support ✅ Supported (anchors to root) ❌ Not supported
Security Impact Prevents committing sensitive data to repository Prevents including sensitive data in images
Performance Impact Minimal (affects git operations only) Significant (affects build time and image size)

🔑 Key Takeaway

The most critical difference in .dockerignore vs .gitignore is pattern depth behavior. A pattern like node_modules in .gitignore matches at any depth, but in .dockerignore it only matches at the root. Use **/node_modules in .dockerignore for recursive matching.

Syntax Comparison: .dockerignore vs .gitignore

Understanding the syntax differences between .dockerignore and .gitignore is crucial for avoiding common mistakes.

1. Pattern Depth: The Most Important Difference

This is where most developers make mistakes when working with .dockerignore vs .gitignore.

.gitignore Behavior

node_modules
*.log
temp

Matches at ANY depth:

  • ✓ node_modules/
  • ✓ src/node_modules/
  • ✓ deep/nested/node_modules/
  • ✓ app.log
  • ✓ logs/error.log
  • ✓ temp/ and src/temp/

.dockerignore Behavior 

node_modules
*.log
temp

Matches at ROOT only:

  • ✓ node_modules/
  • ✗ src/node_modules/ (NOT matched!)
  • ✓ app.log (anywhere, * is recursive)
  • ✓ logs/error.log (anywhere)
  • ✓ temp (root only)
  • ✗ src/temp/ (NOT matched!)

For recursive matching, use:

**/node_modules
**/temp

2. Leading Slash Behavior

.gitignore

/config
/dist
/build

✅ Leading slash is supported:

  • ✓ Anchors pattern to repository root
  • ✓ /config only matches root config/
  • ✗ Does NOT match src/config/

.dockerignore

/config
/dist
/build

❌ Leading slash NOT supported:

  • ⚠️ May be ignored or cause errors
  • ⚠️ Behavior is undefined

Use instead (no slash):

config
dist
build

3. Exception Patterns (!)

Both .dockerignore and .gitignore support exception patterns, but with subtle differences.

.gitignore Example

*.log
!important.log

logs/
!logs/error.log

dist/
!dist/assets/

✅ Excludes all .log files except important.log

✅ Excludes logs/ directory except error.log

✅ More forgiving with order

.dockerignore Example 

*.log
!important.log

**/logs/
!**/logs/error.log

dist/
!dist/assets/

⚠️ Must use **/ for directory patterns

⚠️ Order matters more than .gitignore

⚠️ Later rules can override earlier ones

4. Wildcard Patterns

Pattern .gitignore .dockerignore
*.log Matches .log files at any depth Matches .log files at any depth
temp Matches temp at any depth Matches temp at ROOT only
**/temp Matches temp at any depth Matches temp at any depth
temp/** Matches everything inside temp/ Matches everything inside temp/
**/*.log Matches .log files at any depth Matches .log files at any depth

Pattern Matching Rules: .dockerignore vs .gitignore

Let's examine specific pattern examples and how they behave differently in .dockerignore vs .gitignore.

Pattern .gitignore Matches .dockerignore Matches
node_modules
  • ✓ node_modules/
  • ✓ src/node_modules/
  • ✓ app/lib/node_modules/
  • ✓ node_modules/
  • ✗ src/node_modules/
  • ✗ app/lib/node_modules/
**/node_modules
  • ✓ node_modules/
  • ✓ src/node_modules/
  • ✓ app/lib/node_modules/
  • ✓ node_modules/
  • ✓ src/node_modules/
  • ✓ app/lib/node_modules/
/dist
  • ✓ dist/ (root only)
  • ✗ src/dist/
  • ⚠️ Undefined behavior
  • ⚠️ Don't use leading slash
*.env
  • ✓ .env
  • ✓ config/.env
  • ✓ test.env
  • ✓ .env
  • ✓ config/.env
  • ✓ test.env
temp/
  • ✓ temp/
  • ✓ src/temp/
  • ✓ All nested temp/ dirs
  • ✓ temp/ (root only)
  • ✗ src/temp/

⚠️ Common Mistake Alert

The #1 mistake when comparing .dockerignore vs .gitignore:

Copying your .gitignore patterns directly to .dockerignore without adding **/ prefixes.

This will cause nested directories to NOT be excluded in Docker builds, potentially including sensitive files or bloating your image size!

Wrong approach:

cp .gitignore .dockerignore

Better approach:

# Review each pattern and add **/ where needed
node_modules      →  **/node_modules
temp              →  **/temp
.env              →  **/.env

Real-World Examples: .dockerignore vs .gitignore

Let's look at practical examples for different project types to understand when and how to use .dockerignore vs .gitignore.

Example 1: Node.js Application

.gitignore

# Dependencies
node_modules

# Build outputs
dist
build
*.js.map

# Environment files
.env
.env.local
.env.*.local

# IDE
.vscode
.idea
*.swp

# OS files
.DS_Store
Thumbs.db

# Logs
logs
*.log
npm-debug.log*

# Test coverage
coverage
.nyc_output

Prevents committing dependencies, build artifacts, and IDE files to Git.

.dockerignore

# Dependencies (installed in image)
**/node_modules
npm-debug.log*

# Build artifacts (not needed)
**/dist
**/build

# Development files
.git
.gitignore
**/.vscode
**/.idea
**/*.swp

# Environment files
**/.env
**/.env.*

# Testing
**/coverage
**/.nyc_output
**/test
**/*.test.js

# Documentation
README.md
CONTRIBUTING.md
docs

# CI/CD
.github
.gitlab-ci.yml
Jenkinsfile

Reduces Docker image size by excluding dev dependencies, tests, and docs. Note the **/ prefixes!

Key Difference: .gitignore excludes files from version control, while .dockerignore excludes them from the Docker build context. The .dockerignore file is more aggressive, excluding even committed files like README.md to reduce image size.

Example 2: Python/Django Application

.gitignore

# Python
__pycache__
*.py[cod]
*$py.class
*.so

# Virtual environment
venv
env
.venv

# Django
*.log
db.sqlite3
db.sqlite3-journal
media
staticfiles

# Environment
.env
.env.local

# IDE
.vscode
.idea
*.swp

# Testing
.pytest_cache
.coverage
htmlcov

.dockerignore

# Python cache
**/__pycache__
**/*.py[cod]
**/*$py.class

# Virtual environments
**/venv
**/env
**/.venv

# Local database
**/*.sqlite3

# Environment files
**/.env
**/.env.*

# Development files
.git
.gitignore
**/.vscode
**/.idea

# Testing
**/tests
**/.pytest_cache
**/.coverage
**/htmlcov

# Documentation
README.md
docs
*.md

# Local media/static
media
staticfiles

# CI/CD
.github
.gitlab-ci.yml

Important: Note how __pycache__ becomes **/__pycache__ in .dockerignore. This is the critical syntax difference between .dockerignore vs .gitignore!

Example 3: PHP/Laravel Application

.gitignore

# Laravel
vendor
node_modules
.env
.env.backup
.phpunit.result.cache
Homestead.json
Homestead.yaml
npm-debug.log
yarn-error.log

# Storage
storage/*.key
storage/framework/cache/*
storage/framework/sessions/*
storage/framework/testing/*
storage/framework/views/*
storage/logs/*

# IDE
.vscode
.idea
*.swp

# Build
public/build
public/hot
public/storage

Find more .gitignore templates at gitignores.com.

.dockerignore

# Dependencies (reinstalled in container)
**/vendor
**/node_modules

# Environment files
**/.env
**/.env.*

# Development files
.git
.gitignore
**/.vscode
**/.idea
**/*.swp

# Laravel storage (handled by volumes)
storage/app/*
storage/framework/cache/*
storage/framework/sessions/*
storage/framework/views/*
storage/logs/*
!storage/app/.gitignore
!storage/app/public/.gitignore

# Testing
**/tests
phpunit.xml
.phpunit.result.cache

# Build artifacts
**/public/build
**/public/hot

# Documentation
README.md
*.md
docs

💡 Pro Tip: When to Use Which

  • ✓ .gitignore: Use for files you never want in version control (credentials, IDE configs, OS files)
  • ✓ .dockerignore: Use for files you don't want in your Docker image (tests, docs, dev tools)
  • ✓ Both: Sensitive files like .env should be in BOTH files for double protection

Best Practices: .dockerignore vs .gitignore

Follow these best practices to use .dockerignore and .gitignore effectively in your projects.

Best Practices for .gitignore

  • 1

    Use template generators

    Start with templates from gitignores.com for your language/framework, then customize for your project.

  • 2

    Keep it organized

    Group patterns by category (dependencies, build artifacts, IDE files, OS files) with comments.

  • 3

    Use global .gitignore for IDE/OS files

    Configure a global .gitignore (~/.gitignore_global) for IDE and OS-specific files, keep project .gitignore for project-specific patterns.

  • 4

    Always ignore credentials

    Include .env, secrets/, credentials.json, and any file containing API keys or passwords.

  • 5

    Test your patterns

    Use git check-ignore -v path/to/file to verify which .gitignore rule matches a file.

Best Practices for .dockerignore

  • 1

    Always use **/ for recursive patterns

    Unlike .gitignore, patterns in .dockerignore only match at root by default. Use **/pattern to match at any depth.

  • 2

    Exclude version control

    Always include .git, .gitignore, and other VCS files – they're not needed in Docker images.

  • 3

    Exclude documentation and tests

    README.md, docs/, tests/ should usually be excluded to reduce image size.

  • 4

    Be aggressive with exclusions

    The .dockerignore file should be more aggressive than .gitignore. When in doubt, exclude it – you can always add it back if needed.

  • 5

    Measure the impact

    Run docker image ls before and after optimizing your .dockerignore to see size improvements.

  • 6

    Never use leading slashes

    Unlike .gitignore, .dockerignore doesn't support leading slashes. Use pattern instead of /pattern.

Universal Best Practices (Both Files)

  • ✓

    Add comments

    Explain why certain patterns are included, especially non-obvious ones.

  • ✓

    Commit both files

    Both .dockerignore and .gitignore should be committed to your repository.

  • ✓

    Review regularly

    Update both files as your project evolves and new patterns emerge.

  • ✓

    Double-protect sensitive data

    Critical files like .env should appear in BOTH .gitignore and .dockerignore for defense in depth.

Common Mistakes: .dockerignore vs .gitignore

Avoid these common pitfalls when working with .dockerignore and .gitignore files.

❌

Mistake #1: Copying .gitignore to .dockerignore

Many developers simply copy their .gitignore to .dockerignore, but this doesn't work due to the different pattern matching rules in .dockerignore vs .gitignore.

❌ Wrong (from .gitignore):

node_modules
__pycache__
temp
dist

✅ Correct (.dockerignore):

**/node_modules
**/__pycache__
**/temp
**/dist
❌

Mistake #2: Using Leading Slashes in .dockerignore

Leading slashes work in .gitignore but not in .dockerignore.

❌ Wrong (.dockerignore):

/dist
/config
/build

These won't work properly!

✅ Correct (.dockerignore):

dist
config
build

No leading slashes needed!

❌

Mistake #3: Not Excluding .git Directory in .dockerignore

Forgetting to exclude .git in your .dockerignore wastes space and includes sensitive history in your Docker images.

✅ Always include in .dockerignore:

.git
.gitignore
.gitattributes
.github
❌

Mistake #4: Forgetting to Exclude Dev Dependencies

Including test files, dev tools, and documentation in Docker images unnecessarily increases image size.

✅ Exclude from .dockerignore:

# Testing
**/tests
**/*.test.js
**/*.spec.js
**/coverage
**/.pytest_cache

# Documentation
README.md
CHANGELOG.md
docs
**/*.md

# CI/CD
.github
.gitlab-ci.yml
Jenkinsfile
❌

Mistake #5: Not Having a .dockerignore at All

Many developers don't realize they need a .dockerignore file and rely only on .gitignore. This is a critical mistake in the .dockerignore vs .gitignore comparison.

Without .dockerignore:

  • • Build context includes ALL files (even .git history)
  • • Slower builds (more data sent to Docker daemon)
  • • Larger images (unnecessary files included)
  • • Potential security issues (sensitive files in image)
❌

Mistake #6: Ignoring Cache and Log Files Only in .gitignore

Files like logs and caches should be in BOTH .gitignore and .dockerignore.

✅ Include in BOTH files: 

*.log
**/logs/
**/.cache/
**/tmp/
**/temp/

⚡ Quick Checklist

Before pushing code, verify:

  • .dockerignore exists and uses **/ for recursive patterns
  • No leading slashes in .dockerignore
  • .git directory excluded in .dockerignore
  • Sensitive files (.env) in BOTH files
  • Dev dependencies and tests excluded from .dockerignore

FAQ: .dockerignore vs .gitignore

What's the main difference between .dockerignore vs .gitignore?

.gitignore controls what Git tracks in version control, while .dockerignore controls what Docker includes when building images. The key technical difference is that .gitignore patterns match at any depth by default, while .dockerignore patterns only match at the root unless you use **/.

Can I just copy my .gitignore to .dockerignore?

No, this is a common mistake! While both files use similar syntax, their pattern matching behavior is different. In .dockerignore, you need to add **/ prefix to patterns that should match at any depth (e.g., **/node_modules instead of node_modules). Also, .dockerignore doesn't support leading slashes.

Do I need both .dockerignore and .gitignore?

Yes, if you use both Git and Docker. They serve different purposes at different stages of your development workflow. .gitignore protects your repository, while .dockerignore optimizes your Docker builds and images. Many files should appear in BOTH files (like .env files) for defense in depth.

Why is my .dockerignore pattern not working?

Most likely, you're missing the **/ prefix. Unlike .gitignore, patterns in .dockerignore only match at the root directory by default. To match nested directories, use **/pattern. Also check if you're using a leading slash (/pattern), which doesn't work in .dockerignore.

Where can I find .gitignore templates?

Check out gitignores.com for comprehensive .gitignore templates for virtually any language, framework, or IDE. These templates are community-maintained and regularly updated.

Should README.md be in .dockerignore or .gitignore?

README.md should typically be in your .dockerignore (to reduce image size) but NOT in your .gitignore (it should be version controlled). This illustrates a key difference in .dockerignore vs .gitignore: not everything excluded from Docker needs to be excluded from Git.

How do I test my .dockerignore patterns?

Build your Docker image and check the size with docker image ls. You can also use docker build --progress=plain . to see verbose output. To see what's being sent to the build context, temporarily rename your .dockerignore and compare build times and image sizes.

Can I have multiple .dockerignore files?

No, unlike .gitignore which can be nested in subdirectories, Docker only supports a single .dockerignore file at the root of your build context. This is another key difference in .dockerignore vs .gitignore behavior.

What happens if I don't have a .dockerignore file?

Without a .dockerignore, Docker sends ALL files in your build context to the Docker daemon, including .git history, node_modules, test files, and documentation. This leads to slower builds, larger images, longer upload/download times, and potential security issues if sensitive files are included.

Should .env files be in both .dockerignore and .gitignore?

Absolutely yes! .env files contain sensitive credentials and should be excluded from both version control (.gitignore) and Docker images (.dockerignore). This is a critical security practice when working with .dockerignore vs .gitignore. Use **/.env in .dockerignore to catch .env files at any depth.

Conclusion: Mastering .dockerignore vs .gitignore

Understanding the differences between .dockerignore and .gitignore is essential for modern development workflows. While both files use pattern matching to exclude files, they serve different purposes and have different syntax rules.

Key Takeaways

  • 🎯

    Different Purposes

    .gitignore protects your repository, .dockerignore optimizes your Docker builds

  • ⚙️

    Different Syntax

    .gitignore matches at any depth by default, .dockerignore only at root (use **/)

  • 🔒

    Double Protection

    Sensitive files should appear in BOTH files for defense in depth

  • 📦

    Aggressive Exclusion

    .dockerignore should be more aggressive than .gitignore to minimize image size

Quick Reference Guide

Use Case Use .gitignore Use .dockerignore
Dependency folders ✅ ✅
Environment files (.env) ✅ ✅
IDE configuration ✅ ✅
Build artifacts ✅ ✅
Documentation (README.md) ❌ ✅
Test files ❌ ✅
.git directory ❌ ✅
CI/CD configuration ❌ ✅

Next Steps

  • 1. Review your existing .gitignore and create/update your .dockerignore with proper **/ prefixes
  • 2. Get starter templates from gitignores.com for your language/framework
  • 3. Test your .dockerignore by building your image and comparing sizes before/after
  • 4. Ensure sensitive files (.env, secrets/) are in BOTH files
  • 5. Document your patterns with comments for future team members

Additional Resources

By mastering both .dockerignore and .gitignore, you'll build faster, create smaller images, protect sensitive data, and maintain a clean repository. The key is understanding that while they look similar, .dockerignore vs .gitignore have different purposes, syntax rules, and optimization strategies.