Skill v1.0.1
currentAutomated scan100/1001 files
version: "1.0.1" name: git-best-practices description: Git best practices for ensuring proper .gitignore setup and git workflow management. Use this skill when initializing new projects, working with package managers (npm, pip, etc.), or making git commits.
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:
- Check if `.gitignore` exists: Use
ls -la .gitignoreor check via file system - If `.gitignore` doesn't exist: Create it with appropriate patterns for your project type
- If `.gitignore` exists: Verify it includes the necessary patterns for your package manager
- After creating/updating `.gitignore`: Verify it's working with
git statusto 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.Pythonenv/venv/ENV/env.bak/venv.bak/.venvpip-log.txtpip-delete-this-directory.txt.pytest_cache/.coveragehtmlcov/*.egg-info/dist/build/
Rust / cargo
target/Cargo.lock
Go
*.exe*.exe~*.dll*.so*.dylib*.test*.outgo.work
Java / Maven / Gradle
*.class*.log*.jar*.war*.eartarget/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 outputsdist/build/.next/out/*.tsbuildinfo# OS files.DS_Store.DS_Store?._*.Spotlight-V100.Trashesehthumbs.dbThumbs.dbDesktop.ini# Logs*.loglogs/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
- Always check `git status` before committing to see what will be committed:
``bash git status ``
- 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
- If unwanted files appear:
- Check if
.gitignoreexists and has the correct patterns - Update
.gitignoreif needed - Remove files from staging:
git reset HEAD <file> - Verify with
git statusagain
Commit Message Format
Use the existing project format:
feat: TASK-{id} - {description}
Examples:
feat: TASK-123 - Add user authenticationfeat: 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:
- Run
git statusto see what files git is tracking - 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> ``
- Commit the removal:
git commit -m "chore: Remove tracked files that should be ignored" - Verify again with
git status
Project-Specific Considerations
When Initializing a New Project
- Create
.gitignorebefore runningnpm init,pip install, etc. - Include patterns for your package manager
- Initialize git:
git init(if not already initialized) - Verify
.gitignoreis working before proceeding
When Adding New Dependencies
- Check
git statusafter installing packages - Ensure new build artifacts are ignored
- If new file types appear, update
.gitignoreaccordingly
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/ordist/plus Python patterns
Quick Reference Checklist
Before committing:
- [ ]
.gitignoreexists and is appropriate for the project type - [ ] Ran
git statusand 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} - [ ]
.gitignoreis working correctly (ignored files don't appear ingit status)
Common Mistakes to Avoid
- Initializing package managers before creating `.gitignore`
- This can lead to
node_modules/or similar directories being tracked
- Assuming `.gitignore` works retroactively
- Files already tracked by git will continue to be tracked even if added to
.gitignore - Use
git rm --cachedto untrack them
- Committing without checking `git status`
- Always verify what you're committing
- Including sensitive data in commits
- Double-check for
.envfiles, API keys, passwords - If accidentally committed, use
git resetorgit commit --amend(if not pushed)
- Forgetting project-specific patterns
- Different projects need different
.gitignorepatterns - Tailor the
.gitignoreto 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:
# Before committing, verify compilationnpx tsc --noEmit# If errors exist, fix them before committing
Verify no console errors:
# Check for console errors in browseragent-browser console | grep -i "error"# Or check build outputnpm run build 2>&1 | grep -i "error"
Check git status before staging:
# Always check what will be committedgit status# Review changesgit diff# Stage only relevant filesgit add src/scenes/GameScene.ts
Review changes with git diff:
# Review all changesgit diff# Review staged changesgit diff --staged# Review specific filegit diff src/scenes/GameScene.ts
Commit Message Patterns
Format: "feat: TASK-ID - Description"
# Examplesgit 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:
# Always include task IDgit commit -m "feat: TASK-{id} - {description}"# Examplesgit commit -m "feat: US-036 - Fix maze generation error handling"
Use conventional commit types:
# Types: feat, fix, chore, docs, refactor, testgit 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:
# ✅ GOOD: Descriptive but concisegit commit -m "feat: US-040 - Add coin collection sound effect"# ❌ BAD: Too vaguegit commit -m "feat: US-040 - Update code"# ❌ BAD: Too verbosegit 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:
# Before any git operation, check statusgit status# See what files changedgit status --short# See untracked filesgit status --untracked-files=all
Stage only relevant files:
# Stage specific filesgit add src/scenes/GameScene.tsgit add src/scenes/GameOverScene.ts# Don't stage everything# ❌ git add . # Only if you're sure
Commit after verification passes:
# 1. Make changes# 2. Verify TypeScript compilationnpx tsc --noEmit# 3. Verify browser testingagent-browser open http://localhost:3000# 4. Stage filesgit add src/# 5. Commitgit commit -m "feat: TASK-ID - Description"
Update progress.txt before commit:
# Update progress.txt with task completionecho "## Task Complete" >> tasks/progress.txtecho "- [x] All criteria met" >> tasks/progress.txt# Then commitgit add tasks/progress.txtgit commit -m "feat: TASK-ID - Description"