ignore-files-workflow

# 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 ```gitignore # 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 ```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 ``` --- ## Language-Specific Patterns ### Python ```gitignore __pycache__/ *.py[cod] *.egg-info/ *.so .mypy_cache/ .pytest_cache/ .ruff_cache/ .venv/ venv/ .coverage htmlcov/ ``` ### Node.js / JavaScript ```gitignore node_modules/ npm-debug.log .npm/ package-lock.json yarn.lock dist/ .next/ .nuxt/ ``` ### Go ```gitignore *.exe *.test vendor/ *.out go.sum ``` ### Rust ```gitignore target/ Cargo.lock *.rlib *.rmeta ``` ### General Development (All Languages) ```gitignore *.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 ```gitignore # 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 ```dockerignore # 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: ```gitignore # 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: ```gitignore # 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 ```gitignore # BAD: Matches too much * *.py* config/ ``` ### ✅ Specific Patterns ```gitignore # GOOD: Precise patterns *.pyc *.pyo __pycache__/ config/*.local !config/template.yml ``` ### ❌ Missing Comments ```gitignore .DS_Store Thumbs.db .vscode/ ``` ### ✅ Well-Documented