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:

   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:

   # 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:

# Before committing, verify compilation
npx tsc --noEmit

# If errors exist, fix them before committing

Verify no console errors:

# 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:

# 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:

# 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"

# 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:

# 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:

# 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:

# ✅ 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:

# 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:

# 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:

# 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:

# 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"