ignore-files-workflow

Auto-activate when: Working with .gitignore, .dockerignore, .specstory/, or when user mentions ignore files, version control organization, or Docker build context.

Comprehensive guidelines for maintaining .gitignore and .dockerignore files with proper organization, synchronization, and best practices.

---

Purpose

Maintain .gitignore and .dockerignore files to:

• Exclude unnecessary files from Git version control
• Reduce Docker build context and image sizes
• Prevent accidental commits of secrets and credentials
• Improve build performance
• Keep repositories clean and focused

---

Quick Reference

Key Principles

1. Alphabetical ordering - Within sections, sort entries alphabetically (case-sensitive)
2. Section organization - Use comments to group related patterns
3. Synchronization - Keep shared entries consistent between .gitignore and .dockerignore
4. Specificity - Use precise patterns, avoid overly broad rules
5. Documentation - Comment platform-specific or non-obvious patterns
6. Consistency - Review and maintain quarterly

File Organization Structure

# Comment describing section
specific-entry/
pattern-*.ext
another-entry.xyz

# Next section
other-entry/

---

Alphabetical Ordering Rules

• All entries within sections must be in alphabetical order
• Case-sensitive ordering: uppercase letters before lowercase (ASCII sorting)
• Special characters sorted by ASCII value
• Sections themselves can be organized logically
• Makes files easier to scan and prevents duplicate patterns

Example:

# Build artifacts (alphabetical)
build/
dist/
*.egg-info/

# IDEs (alphabetical)
.idea/
.vscode/
*.swp

---

Synchronization Rules

Entries in Both .gitignore and .dockerignore

These should appear in both files (keep in sync):

# Build artifacts
build/
dist/
*.egg-info/

# Python bytecode
__pycache__/
*.pyc
*.pyo

# Testing outputs
.coverage
.pytest_cache/
htmlcov/

# Environment files
.env
.env.*

# Virtual environments
.venv/
venv/

# Temporary files
tmp/
temp/
*.tmp

# Logs
*.log
logs/

# OS files
.DS_Store
Thumbs.db

# Type checking (Python)
.mypy_cache/

Entries ONLY in .gitignore

# Dev dependencies (keep locally)
.venv/
venv/
ENV/

# IDE configuration (version control is optional)
.idea/
.vscode/
*.swp
*~

# Test coverage reports
htmlcov/

Entries ONLY in .dockerignore

# Git metadata
.git/
.gitattributes
.gitignore

# Documentation (don't need in image)
*.md
docs/

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

# Development tools
.devcontainer/

# Testing (keep in git, exclude from Docker)
tests/
.spec/
*.test.js

# SpecStory artifacts
.specstory/

Why Synchronization Matters

• Consistency - Reduced confusion across build environments
• Maintenance - Less duplicated pattern management
• Security - Same files excluded from both Git and Docker
• Performance - Aligned optimization rules

---

.gitignore Best Practices

What to Include ✅

Build artifacts:

• build/, dist/, *.egg-info/, bin/, lib/, out/

Dependencies:

• node_modules/, .venv/, venv/, vendor/, packages/

Compiled code:

• *.pyc, *.pyo, __pycache__/, *.o, *.so

Test outputs:

• .pytest_cache/, .coverage, htmlcov/, .tox/, .nox/

Environment files:

• .env (secrets), .env.* (except .env.example)

Logs:

• *.log, logs/

OS files:

• .DS_Store, Thumbs.db, Desktop.ini

IDE files:

• .vscode/, .idea/, *.swp, *.swo, *~

Temporary files:

• tmp/, temp/, *.tmp

What NOT to Include ❌

Source code:

• Never ignore application code or tests

Configuration templates:

• .env.example, config.example.yml (provide examples)

Project documentation:

• README.md, docs/, *.md (unless auto-generated)

Essential config:

• pyproject.toml, package.json, Dockerfile

---

.gitignore Complete Template

# Python
__pycache__/
*.egg-info/
*.py[cod]
*.pyo
*.so
.Python

# Distribution / packaging
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/

# Virtual environments
.venv/
venv/
ENV/
env/

# Testing
.coverage
.nox/
.pytest_cache/
.tox/
htmlcov/

# Type checking
.dmypy.json
.mypy_cache/
.pytype/
dmypy.json

# Linting
.ruff_cache/

# Jupyter
.ipynb_checkpoints/
*.ipynb_checkpoints

# Environment
.env
.env.*
!.env.example

# IDEs
.idea/
.vscode/
*.swp
*.swo
*~

# OS
.DS_Store
Thumbs.db

# Logs
*.log
logs/

# Temporary
temp/
tmp/
*.tmp

---

.dockerignore Best Practices

What to Include ✅

Version control:

• .git/, .gitignore, .gitattributes

Documentation:

• README.md, docs/, *.md (not needed in image)

CI/CD:

• .github/, .gitlab-ci.yml, Jenkinsfile

Development:

• .devcontainer/, .vscode/, .idea/

Testing:

• tests/, .spec/, .specstory/, *.test.js

Build artifacts:

• build/, dist/, node_modules/, *.egg-info/

Environment:

• .env, .env.*

Logs:

• *.log, logs/

OS files:

• .DS_Store, Thumbs.db

What to KEEP ✅

Source code - Code needed in the image

Dependencies files:

• requirements.txt, package.json, Gemfile, go.mod

Configuration - Config needed at runtime

Assets - Static files served by the application

---

.dockerignore Complete Template

# Git
.git/
.gitattributes
.gitignore

# Documentation
*.md
docs/

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

# Development
.devcontainer/
.idea/
.vscode/

# Testing
.coverage
.pytest_cache/
.spec/
.specstory/
htmlcov/
tests/

# Python
__pycache__/
*.egg-info/
*.pyc
*.pyo
.mypy_cache/
.ruff_cache/

# Virtual environments
.venv/
venv/

# Build artifacts
build/
dist/

# Environment files
.env
.env.*

# Logs
*.log
logs/

# OS
.DS_Store
Thumbs.db

# Temporary
temp/
tmp/
*.tmp

---

Language-Specific Patterns

Python

__pycache__/
*.py[cod]
*.egg-info/
*.so
.mypy_cache/
.pytest_cache/
.ruff_cache/
.venv/
venv/
.coverage
htmlcov/

Node.js / JavaScript

node_modules/
npm-debug.log
.npm/
package-lock.json
yarn.lock
dist/
.next/
.nuxt/

Go

*.exe
*.test
vendor/
*.out
go.sum

Rust

target/
Cargo.lock
*.rlib
*.rmeta

General Development (All Languages)

*.swp
*.swo
*~
.DS_Store
Thumbs.db
.vscode/
.idea/

---

SpecStory Integration

.specstory Directory Management

The .specstory/ directory contains SpecStory extension artifacts (chat history, project metadata, backups).

Recommended .gitignore Entry

# SpecStory artifacts (optional - exclude chat history from version control)
.specstory/history/

# SpecStory AI rules backups (optional - if you version control separately)
.specstory/ai_rules_backups/

# Full .specstory exclusion (if not using SpecStory)
.specstory/**

Recommended .dockerignore Entry

# SpecStory artifacts (development tool, not needed in image)
.specstory/

When to Keep .specstory in Git

• Valuable for project context and decision history
• Useful for onboarding and meta-analysis
• Share chat history with team

When to Exclude .specstory

• When chat history contains sensitive information
• When you want minimal repository bloat
• When .specstory is auto-generated

---

Project-Specific Customization

Adding Custom Patterns

For project-specific artifacts:

# Project-specific data
data/raw/
models/trained/
cache/

# Generated artifacts
api-docs/
coverage-reports/

# Platform-specific
*.local

Excluding Important Files with Negation

Use ! to override ignore patterns:

# Ignore all .env files
.env.*

# Except the example template
!.env.example

# Ignore all configs
config/*.yml

# Except the template
!config/template.yml

# Ignore Python cache but keep specific file
__pycache__/
!__pycache__/.gitkeep

---

Common Mistakes to Avoid

❌ Too Broad Patterns

# BAD: Matches too much
*
*.py*
config/

✅ Specific Patterns

# GOOD: Precise patterns
*.pyc
*.pyo
__pycache__/
config/*.local
!config/template.yml

❌ Missing Comments

.DS_Store
Thumbs.db
.vscode/

✅ Well-Documented

# OS files
.DS_Store    # macOS
Thumbs.db    # Windows

# IDEs
.vscode/     # VS Code
.idea/       # JetBrains

❌ Accidentally Ignoring Important Files

*.example    # Too broad, catches .example files you need
.env.*       # Without negation for .env.example
test/        # Might ignore real tests

✅ Precise Patterns with Exceptions

.env
.env.*
!.env.example

tests/       # Only the tests directory
!tests/.gitkeep

---

Maintenance Guidelines

Regular Review Schedule

• Quarterly review - Check for obsolete patterns
• New tool/framework - Add patterns immediately after adoption
• Performance issues - Review when builds or operations slow down
• Team feedback - Incorporate suggestions from team members

Review Checklist

• [ ] All patterns alphabetically sorted within sections
• [ ] No duplicate patterns
• [ ] Comments describe each section clearly
• [ ] Patterns are specific, not overly broad
• [ ] No accidentally ignored important files
• [ ] .env.example and templates NOT ignored
• [ ] Docker build context size is reasonable
• [ ] Tests confirmed still tracked in Git

Testing Ignore Patterns

# Check what Git ignores (shows all ignored files)
git status --ignored

# Check what .gitignore would ignore (dry run)
git check-ignore -v *

# List what's being tracked
git ls-files

# Verify specific file not ignored
git check-ignore -v path/to/file.txt

# Docker build context size
docker build --no-cache . 2>&1 | grep "Sending build context"

# See what Docker would send (requires buildkit)
DOCKER_BUILDKIT=1 docker build --progress=plain . 2>&1 | head -20

---

Verification Checklist

Before committing changes to ignore files:

• [ ] All patterns are in alphabetical order within sections
• [ ] Each section has a descriptive comment header
• [ ] No overly broad patterns (*, .*)
• [ ] Templates and examples NOT ignored (.env.example, config.example.yml)
• [ ] Critical files still tracked: git status | grep -E "package.json|requirements.txt|Dockerfile"
• [ ] No duplicate patterns between sections
• [ ] Platform-specific patterns are commented (# macOS, # Windows)
• [ ] .specstory/ handled appropriately (included/excluded consistently)
• [ ] Docker build context is reasonable size
• [ ] git status --ignored shows expected ignored files
• [ ] Run make test or equivalent test suite passes (if applicable)

---

Complete Example: Synchronized Python Project

.gitignore

# Build artifacts
build/
dist/
*.egg-info/

# Python
__pycache__/
*.py[cod]
*.pyo
*.so
.Python

# Virtual environments
.venv/
venv/
ENV/
env/

# Testing
.coverage
.pytest_cache/
.tox/
htmlcov/

# Type checking
.mypy_cache/
.dmypy.json
dmypy.json
.pytype/

# Linting
.ruff_cache/

# Jupyter
.ipynb_checkpoints/
*.ipynb_checkpoints

# Environment
.env
.env.*
!.env.example

# IDEs
.idea/
.vscode/
*.swp
*.swo
*~

# OS
.DS_Store
Thumbs.db

# Logs
*.log
logs/

# Temporary
temp/
tmp/
*.tmp

# SpecStory (optional)
.specstory/history/

.dockerignore

# Git
.git/
.gitattributes
.gitignore

# Documentation
*.md
docs/

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

# Development
.devcontainer/
.idea/
.vscode/

# Testing
.coverage
.pytest_cache/
.spec/
.specstory/
htmlcov/
tests/

# Python
__pycache__/
*.egg-info/
*.pyc
*.pyo
.mypy_cache/
.ruff_cache/

# Virtual environments
.venv/
venv/

# Build artifacts
build/
dist/

# Environment files
.env
.env.*

# Logs
*.log
logs/

# OS
.DS_Store
Thumbs.db

# Temporary
temp/
tmp/
*.tmp

---

Performance Impact

Git Perspective

• Smaller .git directory
• Faster git status / git add
• Faster clones and fetches
• Reduced disk space

Docker Perspective

• Faster build context transfer
• Smaller Docker layers
• Reduced image size (if context files not copied)
• Improved build times

Measurements

# Check .git size
du -sh .git

# Check what's in Docker build context
docker build --progress=plain . 2>&1 | grep "Sending build context"

---

Synchronization Workflow

When Adding New Patterns

1. Identify which files should be ignored (Git, Docker, or both)
2. Add to appropriate file(s)
3. Sort alphabetically within section
4. Add comment if non-obvious
5. Test with git status --ignored or Docker build
6. Verify important files still tracked

Pattern Consistency

• Shared entries - Must be in both files if filtering is common
• Version control - Document why entry needed
• Review together - Changes should consider both files