FoundryVTT/.gitignore.README.md

.gitignore Configuration for JPD Portal

This document explains the .gitignore configuration for the JPD Portal project.

Critical Files Protected

The following sensitive files are NEVER committed to version control:

🔐 Security & Credentials

• src/JPD.env - Contains API keys (Jira, Confluence, Claude API)
• *.env files - All environment variable files
• secrets.json - ASP.NET Core user secrets

💾 Databases & Data

• src/JpdPortal/data/vectors.db - SQLite vector embeddings database
• src/JpdPortal/data/uploads/* - User-uploaded requirements files (except .gitkeep)
• All .db, .sqlite, .sqlite3 files

🏗️ Build Artifacts

• bin/ and obj/ directories - .NET build outputs
• Debug/ and Release/ - Build configurations
• *.dll, *.exe, *.pdb - Compiled binaries

Directory Structure Preservation

Some directories need to exist but their contents should not be committed:

src/JpdPortal/data/
├── uploads/
│   └── .gitkeep          ← Tracked to preserve directory
│   └── *.txt             ← Ignored (user uploads)
└── vectors.db            ← Ignored (SQLite database)

The .gitkeep file ensures the uploads/ directory structure is preserved in git.

Pattern Categories

The .gitignore is organized into these sections:

1. Claude Code - IDE-specific files
2. Project-Specific Sensitive Files - JPD.env, databases, uploads
3. .NET Core / ASP.NET Core - Build artifacts, Visual Studio files
4. AI/ML Specific - ONNX models, training artifacts, vector databases
5. Blazor Specific - WebAssembly cache, generated assets
6. Testing - Test results and coverage reports
7. Environment Variables & Secrets - All .env files
8. Database Files - SQLite and other database files
9. Logs - Application log files
10. OS Files - Windows, macOS, Linux system files
11. Backup Files - .bak, .old, .tmp files
12. Node.js - npm packages (if used for frontend)
13. Python - pycache, venv (if used for ML scripts)

Already Tracked Files

If you see modified files in bin/ or obj/ directories that should be ignored, they were tracked before the .gitignore was updated. To remove them:

# Remove build artifacts from git tracking
git rm -r --cached src/JpdPortal/bin/
git rm -r --cached src/JpdPortal/obj/

# Commit the changes
git commit -m "chore: remove build artifacts from git tracking"

Note: The --cached flag removes files from git tracking but keeps them on your local filesystem.

Verifying Ignore Patterns

To check if a file will be ignored:

# Check specific files
git check-ignore -v src/JPD.env
git check-ignore -v src/JpdPortal/data/vectors.db

# Check entire directory
git check-ignore -v src/JpdPortal/bin/*

Expected output for ignored files:

.gitignore:199:*.env    src/JPD.env

Best Practices

✅ DO:

• Always verify src/JPD.env is NOT staged before committing
• Check git status before commits to ensure no sensitive data
• Use git check-ignore to verify patterns
• Keep the .gitkeep file in the uploads directory

❌ DON'T:

• Never commit API keys or credentials
• Never force-add ignored files with git add -f
• Don't commit build artifacts (bin/, obj/)
• Don't commit database files with user data
• Don't commit user-uploaded files

Emergency: Removing Sensitive Data

If you accidentally committed sensitive data (like JPD.env), you need to remove it from git history:

# Remove file from git history (WARNING: rewrites history)
git filter-branch --force --index-filter \
  "git rm --cached --ignore-unmatch src/JPD.env" \
  --prune-empty --tag-name-filter cat -- --all

# Force push (if already pushed to remote)
git push origin --force --all

Better approach: Use GitHub's BFG Repo-Cleaner or contact repository admin.

Environment Setup for New Developers

When cloning this repository:

1. Copy the environment template:

   cp src/JPD.env.example src/JPD.env
   

2. Edit src/JPD.env with your credentials

3. Verify it's ignored:

   git status
   # Should NOT show JPD.env as untracked
   

4. Create necessary directories:

   mkdir -p src/JpdPortal/data/uploads
   

Maintenance

Review and update this .gitignore when:

• Adding new services with credentials
• Adding new ML models or data storage
• Changing build output directories
• Adding new tools or frameworks
• Team reports accidental commits of ignored files

---

Last Updated: 2025-10-20 Project: JPD Portal v1.0.0