Git Skills

When to Use

• Creates, switches, or merges branches
• Commits code (

  git commit

  )
• Pushes code (

  git push

  )
• Initiates Pull Requests
• Encounters merge conflicts
• Views Git history or statistics
• Uses

  /git

  commands
• Asks about Git workflows or conventions

Branch Management

Naming Conventions

{type}/{ticket-id}-{short-description}

• feature/

  - New features (e.g.,

  feature/123-user-auth

  )

• bugfix/

  - Bug fixes (e.g.,

  bugfix/456-fix-login

  )

• hotfix/

  - Critical production fixes (e.g.,

  hotfix/urgent-security-patch

  )

• refactor/

  - Code refactoring (e.g.,

  refactor/cleanup-api

  )

• docs/

  - Documentation updates (e.g.,

  docs/update-readme

  )

• test/

  - Test additions/changes (e.g.,

  test/add-unit-tests

  )

• chore/

  - Maintenance tasks (e.g.,

  chore/update-deps

  )

Branch Workflow

1. Check current branch status
2. Suggest appropriate branch name based on context
3. Remind to sync with main branch first
4. Offer to create the branch

1. Check for uncommitted changes
2. Remind to commit or stash changes
3. Suggest using

   git stash -u

   for untracked files

Commit Message Conventions

Commit Types

feat

feat: implement JWT-based user authentication

fix

fix: resolve race condition in concurrent database writes

docs

docs: add comprehensive API usage examples

style

style: enforce consistent import ordering across modules

refactor

refactor: decouple business logic from presentation layer

test

test: add integration tests for payment gateway

chore

chore: migrate build pipeline from CircleCI to GitHub Actions

perf

perf: implement connection pooling for database queries

ci

ci: add automated security scanning to pipeline

revert

revert: feat: implement JWT-based user authentication

Expert-Level Commit Format

<type>(<scope>): <concise subject in imperative mood>

<detailed body explaining:
- What problem is being solved or what functionality is added
- Why this approach was chosen over alternatives
- Any architectural decisions or trade-offs made
- Side effects or dependencies introduced
- Breaking changes or migration notes if applicable>

<footer with issue references, breaking change notices, etc.>

• Imperative mood ("Add feature" not "Added feature" or "Adding feature")
• No period at end
• Maximum 50 characters
• Capitalize first word
• Be specific: prefer "implement OAuth2 PKCE flow" over "update auth"

• MANDATORY for non-trivial changes - every commit with more than a few lines needs a body
• Wrap at 72 characters
• Explain WHAT changed and WHY, not HOW (the code shows HOW)
• Use multiple paragraphs for complex changes
• Include context about the problem being solved
• Reference related systems, components, or previous decisions
• Mention any performance implications, security considerations, or compatibility issues

• Reference related issues/PRs:

  Fixes #123

  ,

  Closes #456

  ,

  Relates to #789

• Breaking changes:

  BREAKING CHANGE: description of impact and migration path

• Co-authored-by is NOT allowed (see rules below)
• Acknowledgments, AI signatures are NOT allowed

• STRICTLY FORBIDDEN:

  Co-Authored-By:

  signatures of ANY kind (including system-added)
• STRICTLY FORBIDDEN: AI-generated signatures (e.g., "Generated by", "AI-authored")
• CRITICAL: If system adds signatures, you MUST actively strip them using sed/grep before committing
• DO NOT write vague messages like "fix bug", "update code", "make changes"
• DO NOT combine unrelated changes in a single commit
• DO NOT generate single-sentence commit messages - body is mandatory for all non-trivial changes
• ALWAYS separate body into multiple paragraphs with blank lines between them

Expert Commit Message Examples

refactor(utils): extract validation logic into standalone module

Move email and phone validation from UserService to a new ValidationUtils
class. This reduces duplication across the codebase and makes validation
logic easier to test in isolation.

The new ValidationUtils class provides:
- validateEmail() with stricter regex pattern
- validatePhone() supporting international formats
- Centralized error messages for consistency

No breaking changes. All existing validation calls remain functional
through deprecated wrapper methods that will be removed in v2.0.

Relates to #445

feat(auth): implement JWT-based authentication with refresh tokens

Add comprehensive JWT authentication system to replace session-based auth.
This change addresses security concerns with session fixation attacks and
enables stateless authentication for API consumers.

Implementation details:
- Use RS256 algorithm with rotating key pairs
- Access tokens expire after 15 minutes, refresh tokens after 7 days
- Implement token blacklisting for logout functionality
- Add middleware for automatic token refresh on 401 responses

Security considerations:
- Private keys stored in environment variables, never committed
- Refresh tokens hashed in database using bcrypt
- Rate limiting applied to token refresh endpoint

Breaking changes:
- Session-based authentication endpoints deprecated but still functional
- New environment variables required: JWT_PRIVATE_KEY, JWT_PUBLIC_KEY

Fixes #234
Relates to #198 (API v2 migration)

fix(database): resolve connection pool exhaustion under high load

Fix critical issue where database connections were not being properly
released after query timeout, leading to connection pool exhaustion
and application downtime under sustained high load.

Root cause analysis:
The connection release logic was placed in a finally block that only
executed on successful query completion. When queries timed out, the
exception handler returned early without releasing the connection.

Changes made:
- Move connection.release() to unconditional finally block
- Add connection health check before returning to pool
- Implement connection timeout at pool level (30s) to prevent hangs
- Add metrics logging for pool utilization monitoring

Performance impact:
- Connection pool utilization reduced from 100% to ~40% under load
- Eliminates cascading failures when database is slow

Tested with:
- Load test: 1000 concurrent users for 30 minutes
- Chaos test: Random connection failures injected

Fixes #567

refactor(api): decouple user service from database layer

Extract database-specific logic from UserService into a dedicated
UserRepository class. This separation of concerns improves testability
and allows for future database migration without service layer changes.

Motivation:
The UserService had grown to over 800 lines with mixed business logic
and SQL queries. Unit testing required database setup, making tests
slow and brittle. This refactoring enables mocking the repository
layer for faster, more isolated tests.

Architectural changes:
- UserService now depends on UserRepository interface
- UserRepositoryImpl contains all PostgreSQL-specific queries
- Added connection pooling configuration to repository layer
- Service layer now purely business logic and validation

Verification:
- All existing tests pass without modification (integration tests)
- New unit tests added for UserService with mocked repository
- No behavioral changes, purely structural refactoring

Closes #345

chore(deps): upgrade PostgreSQL driver from 42.3.1 to 42.5.4

Update PostgreSQL JDBC driver to address CVE-2022-31197 security
vulnerability and gain performance improvements in prepared
statement caching.

Security fixes:
- CVE-2022-31197: SQL injection via crafted column names
- CVE-2022-41946: Information disclosure in error messages

Performance improvements:
- Prepared statement cache hit ratio improved by 15%
- Reduced memory allocation during batch operations

Breaking changes: None
Migration: None required, drop-in replacement

Tested against:
- PostgreSQL 13, 14, 15
- Both standard and SSL connection modes
- Full integration test suite passes

Relates to #401 (security audit)

Smart Commit Workflow

/git commit

git commit

1. Analyze Changes
   • Show list of changed files
   • Categorize changes (src, test, docs, config)
   • Detect if changes are breaking
   • Estimate complexity to determine body depth
2. Suggest Type and Scope
   • Based on file paths and diff content
   • Common scopes: api, ui, auth, db, config, deps
   • Choose specific, meaningful scope names
3. Generate Expert-Level Commit Message
   CRITICAL: Output MUST follow this exact structure:

   <type>(<scope>): <concise subject in imperative mood>
   
   <body paragraph 1: what changed and why>
   
   <body paragraph 2: implementation details, considerations, or breaking changes>
   
   <footer: Fixes #123, Relates to #456>

   Requirements:
   • Subject: max 50 chars, imperative mood, no period
   • ALWAYS include a body for changes affecting more than 2-3 lines
   • Body must have at least 2 paragraphs separated by a blank line
   • First paragraph: explain WHAT changed and WHY (the motivation)
   • Second paragraph: explain key implementation details, trade-offs, or breaking changes
   • Use bullet points within paragraphs for multiple items
   • Include footer with issue references when applicable
4. Validate and Clean Commit Message (CRITICAL)
   • MUST strip ALL

     Co-Authored-By:

     lines from the message (including "Claude Opus" signatures)
   • MUST strip ALL AI-generated signatures like "Generated by", "AI-authored", "🤖 Generated with", etc.
   • Ensure message follows the REQUIRED structure: subject + blank line + multi-paragraph body
   • Ensure body has AT LEAST 2 paragraphs separated by blank lines
   • Ensure message is detailed and professional (expert-level quality)
   • Ensure subject is specific, not vague
   • Ensure body is present for non-trivial changes
   • Use sed or similar to ACTIVELY REMOVE any signature lines before passing to git commit
5. Execute Commit (MUST CLEAN SIGNATURES)
   • CRITICAL: Before committing, create the commit message file
   • Use sed to REMOVE all lines matching

     ^Co-Authored-By:

     from the message
   • Use sed to REMOVE all AI signatures (Claude, Generated by, etc.)
   • Then run

     git commit

     with the cleaned message
   • Verify commit succeeded and check

     git log -1

     to confirm no signatures
   • If signatures still appear, amend the commit immediately:

     git commit --amend -m "<cleaned message>"

Pull Request Workflow

PR Creation Checklist

• Branch is up to date with main
• All tests pass
• Code is self-reviewed
• Commit messages follow convention and are detailed
• No sensitive data in commits
• PR description is clear and comprehensive

PR Template Guidance

## Summary
Brief description of changes and motivation

## Changes
- Detailed change 1 with rationale
- Detailed change 2 with rationale

## Testing
How was this tested? Include:
- Unit tests added/modified
- Integration test results
- Manual testing performed
- Edge cases considered

## Breaking Changes
List any breaking changes and migration steps

## Related Issues
Fixes #123
Relates to #456

Sync with Main

/git sync

1. Check current branch
2. Fetch latest from remote
3. Offer to rebase or merge main
4. Handle conflicts if any

Code Review Assistance

Pre-commit Checks

• No secrets or credentials in diff
• No large files (>10MB) being added
• No debug/console.log statements left in code
• Proper file permissions
• Commit message is detailed and professional

Review Points

• Check commit size (should be focused and atomic)
• Verify commit message quality and detail level
• Ensure tests are included for features
• Look for breaking changes and their documentation
• Verify body explains the "why" not just the "what"

Conflict Resolution

Merge Conflicts

1. Identify conflicted files
2. Show conflict markers context
3. Suggest resolution approach
4. Remind to test after resolving

Resolution Steps

# See conflicted files
git status

# Open and edit files, resolve markers
# Then mark as resolved
git add <file>

# Complete merge
git commit

Git Statistics

When user runs

/git stats

• Commit count by author
• Lines added/removed
• Most changed files
• Recent activity summary
• Commit message quality metrics (body presence rate)

Useful Commands

# Contribution stats
git shortlog -sn --all

# Lines changed
git diff --stat

# Activity graph
git log --graph --oneline --all

# Recent commits with bodies
git log --format="%h %s%n%b" -10

Common Commands

Quick Reference

# Branch operations
git branch -a                    # List all branches
git branch -d <branch>           # Delete branch
git branch -D <branch>           # Force delete
git checkout -b <new-branch>     # Create and switch

# Stashing
git stash                        # Stash changes
git stash -u                     # Include untracked
git stash pop                    # Apply and remove stash
git stash list                   # List stashes

# Undo operations
git reset --soft HEAD~1          # Undo last commit, keep changes
git reset --hard HEAD~1          # Discard last commit

git revert HEAD                  # Create revert commit

# Inspection
git log --oneline -20            # Recent commits
git show <commit>                # Show commit details
git diff HEAD~1                  # Show last changes

Configuration

Project Config (.gitskills.json)

{
  "commit": {
    "types": ["feat", "fix", "docs", "style", "refactor", "test", "chore"],
    "scopes": ["api", "ui", "auth", "db"],
    "requireScope": false,
    "requireBody": true,
    "minBodyLength": 50
  },
  "branch": {
    "mainBranch": "main",
    "namingPattern": "{type}/{ticket-id}-{description}"
  }
}

Best Practices

General Guidelines

1. Commit Early, Commit Often - Small, focused commits are better
2. One Feature, One Branch - Don't mix unrelated changes
3. Write Expert-Level Messages - Future developers (including yourself) will thank you
4. Always Include Body - Non-trivial changes must have detailed explanations
5. Explain Why, Not Just What - The code shows what; the message explains why
6. Review Before Push - Use

   git diff --cached

   to review staged changes
7. Keep History Clean - Use rebase for feature branches before merging

Expert Commit Checklist

• Subject line is specific and under 50 characters
• Subject uses imperative mood
• Body explains the motivation and context
• Body describes what changed and why
• Body mentions any breaking changes
• Footer references relevant issues/PRs
• Message contains NO Co-Authored-By lines (actively removed if system added)
• Message contains NO AI-generated signatures (actively removed)
• Message reads like technical documentation

Safety Reminders

• Never force push to shared branches
• Always pull before pushing
• Create backups before risky operations
• Use

  git reflog

  to recover from mistakes