git-best-practices

# Git Best Practices Skill This skill provides comprehensive guidelines for proper git workflow management, with a focus on `.gitignore` setup and preventing accidental commits of unwanted files. ## .gitignore Management ### Critical: Always Check Before Initializing Package Managers **BEFORE** initializing npm, pip, poetry, cargo, or any other package manager: 1. **Check if `.gitignore` exists**: Use `ls -la .gitignore` or check via file system 2. **If `.gitignore` doesn't exist**: Create it with appropriate patterns for your project type 3. **If `.gitignore` exists**: Verify it includes the necessary patterns for your package manager 4. **After creating/updating `.gitignore`**: Verify it's working with `git status` to ensure ignored files don't appear ### Required Patterns by Project Type #### Node.js / npm / yarn / pnpm ``` node_modules/ npm-debug.log* yarn-debug.log* yarn-error.log* pnpm-debug.log* .pnpm-store/ ``` #### Python / pip / poetry ``` __pycache__/ *.py[cod] *$py.class *.so .Python env/ venv/ ENV/ env.bak/ venv.bak/ .venv pip-log.txt pip-delete-this-directory.txt .pytest_cache/ .coverage htmlcov/ *.egg-info/ dist/ build/ ``` #### Rust / cargo ``` target/ Cargo.lock ``` #### Go ``` *.exe *.exe~ *.dll *.so *.dylib *.test *.out go.work ``` #### Java / Maven / Gradle ``` *.class *.log *.jar *.war *.ear target/ build/ .gradle/ .idea/ *.iml ``` ### Universal Patterns (All Projects) These should be included in every `.gitignore`: ``` # Environment files .env .env.local .env.*.local .env.development .env.production .env.test *.env # Build outputs dist/ build/ .next/ out/ *.tsbuildinfo # OS files .DS_Store .DS_Store? ._* .Spotlight-V100 .Trashes ehthumbs.db Thumbs.db Desktop.ini # Logs *.log logs/ npm-debug.log* yarn-debug.log* yarn-error.log* pnpm-debug.log* lerna-debug.log* # Editor files (optional - include if not using shared IDE config) .idea/ .vscode/ *.swp *.swo *~ .project .classpath .settings/ # Temporary files *.tmp *.temp .cache/ ``` ## Git Workflow Best Practices ### Before Committing 1. **Always check `git status`** before committing to see what will be committed: ```bash git status ``` 2. **Review the output carefully**: - Ensure no sensitive files are staged (`.env`, secrets, API keys) - Verify `node_modules/` or other build artifacts aren't included - Check that only intended files are staged 3. **If unwanted files appear**: - Check if `.gitignore` exists and has the correct patterns - Update `.gitignore` if needed - Remove files from staging: `git reset HEAD <file>` - Verify with `git status` again ### Commit Message Format Use the existing project format: ``` feat: TASK-{id} - {description} ``` Examples: - `feat: TASK-123 - Add user authentication` - `feat: TASK-456 - Fix memory leak in data processor` ### Never Commit - **Sensitive files**: `.env`, `.env.local`, any file containing secrets, API keys, passwords - **Build artifacts**: `node_modules/`, `dist/`, `build/`, compiled binaries - **OS files**: `.DS_Store`, `Thumbs.db` - **Large binary files**: Unless using Git LFS (Large File Storage) - **IDE-specific files**: Unless the project explicitly includes them in version control ### Verifying .gitignore Effectiveness After creating or updating `.gitignore`: 1. Run `git status` to see what files git is tracking 2. If ignored files still appear, they may have been previously tracked: ```bash # Remove from git cache (but keep local files) git rm --cached <file> # Or for directories: git rm -r --cached <directory> ``` 3. Commit the removal: `git commit -m "chore: Remove tracked files that should be ignored"` 4. Verify again with `git status` ## Project-Specific Considerations ### When Initializing a New Project 1. Create `.gitignore` **before** running `npm init`, `pip install`, etc. 2. Include patterns for your package manager 3. Initialize git: `git init` (if not already initialized) 4. Verify `.gitignore` is working before proceeding ### When Adding New Dependencies 1. Check `git status` after installing packages 2. Ensure new build artifacts are ignored 3. If new file types appear, update `.gitignore` accordingly ### When Working with Multiple Languages If a project uses multiple languages/frameworks, include patterns for all of them: - Node.js + Python: Include both `node_modules/` and `__pycache__/` - React + Python backend: Include `.next/` or `dist/` plus Python patterns ## Quick Reference Checklist Before committing: - [ ] `.gitignore` exists and is appropriate for the project type - [ ] Ran `git status` and reviewed output - [ ] No sensitive files (`.env`, secrets) are staged - [ ] No build artifacts (`node_modules/`, `dist/`, etc.) are staged - [ ] Commit message follows format: `feat: TASK-{id} - {description}` - [ ] `.gitignore` is working correctly (ignored files don't appear in `git status`) ## Common Mistakes to Avoid 1. **Initializing package managers before creating `.gitignore`** - This can lead to `node_modules/` or similar directories being tracked 2. **Assuming `.gitignore` works retroactively** - Files already tracked by git will continue to be tracked even if added to `.gitignore` - Use `git rm --cached` to untrack them 3. **Committing without checking `git status`** - Always verify what you're committing 4. **Including sensitive data in commits** - Double-check for `.env` files, API keys, passwords - If accidentally committed, use `git reset` or `git commit --amend` (if not pushed) 5. **Forgetting project-specific patterns** - Different projects need different `.gitignore` patterns - Tailor the `.gitignore` to the project's technology stack ## Pre-Commit Checklist Before committing, verify: - [ ] TypeScript compilation passes (`npx tsc --noEmit`) - [ ] No console errors in browser testing - [ ] All success criteria verified - [ ] Progress.txt updated ## Pre-Commit Hooks Consider adding pre-commit hooks for: - TypeScript compilation check - Linter checks - Test execution Document hook setup in project README if implemented. ## Pre-Commit Validation **Run TypeScript compilation check before commit:** ```bash # Before committing, verify compilation npx tsc --noEmit # If errors exist, fix them before committing ``` **Verify no console errors:** ```bash # Check for console errors in browser agent-browser console | grep -i "error" # Or check build output npm run build 2>&1 | grep -i "error" ``` **Check git status before staging:** ```bash # Always check what will be committed git status # Review changes git diff # Stage only relevant files git add src/scenes/GameScene.ts ``` **Review changes with git diff:** ```bash # Review all changes git diff # Review staged changes git diff --staged # Review specific file git diff src/scenes/GameScene.ts ``` ## Commit Message Patterns **Format: "feat: TASK-ID - Description"** ```bash # Examples git commit -m "feat: US-033 - Add wizard character sprite" git commit -m "feat: US-034 - Implement timer countdown" git commit -m "feat: US-035 - Add scene transition animations" ``` **Include task ID for traceability:** ```bash # Always include task ID git commit -m "feat: TASK-{id} - {description}" # Examples git commit -m "feat: US-036 - Fix maze generation error handling" ``` **Use conventional commit types:** ```bash # Types: feat, fix, chore, docs, refactor, test git commit -m "feat: US-037 - Add new feature" git commit -m "fix: US-038 - Fix bug" git commit -m "chore: US-039 - Update dependencies" ``` **Keep messages descriptive but concise:** ```bash # ✅ GOOD: Descriptive but concise git commit -m "feat: US-040 - Add coin collection sound effect" # ❌ BAD: Too vague git commit -m "feat: US-040 - Update code" # ❌ BAD: Too verbose git commit -m "feat: US-040 - Add coin collection sound effect that plays when player collects coin and updates score and triggers animation" ``` ## Workflow Patterns **Check git status before operations:** ```bash # Before any git operation, check status git status # See what files changed git status --short # See untracked files git status --untracked-files=all ``` **Stage only relevant files:** ```bash # Stage specific files git add src/scenes/GameScene.ts git add src/scenes/GameOverScene.ts # Don't stage everything # ❌ git add . # Only if you're sure ``` **Commit after verification passes:** ```bash # 1. Make changes # 2. Verify TypeScript compilation npx tsc --noEmit # 3. Verify browser testing agent-browser open http://localhost:3000 # 4. Stage files git add src/ # 5. Commit git commit -m "feat: TASK-ID - Description" ``` **Update progress.txt before commit:** ```bash # Update progress.txt with task completion echo "## Task Complete" >> tasks/progress.txt echo "- [x] All criteria met" >> tasks/progress.txt # Then commit git add tasks/progress.txt git commit -m "feat: TASK-ID - Description" ```