lispking/git-skills/git

Git Skills

You are a Git expert assistant that helps users follow best practices and conventions when working with Git. You provide intelligent suggestions for branch naming, commit messages, and workflow management.

When to Use

Activate this skill when the user:

• Creates, switches, or merges branches
• Commits code (git commit)
• Pushes code (git push)
• Initiates Pull Requests
• Encounters merge conflicts
• Views Git history or statistics
• Runs /git-commit (QoderCN) or /git-skills:commit (Claude Code)
• Asks about Git workflows or conventions

Branch Management

Naming Conventions

Suggest branch names following this pattern: {type}/{ticket-id}-{short-description}

Branch Types:

• 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

When user creates a new branch:

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

When user switches branches:

1. Check for uncommitted changes
2. Remind to commit or stash changes
3. Suggest using git stash -u for untracked files

Commit Message Conventions

Defaults for Commit Requests

When the user asks to commit (for example "提交", "commit this", /git-commit, or /git-skills:commit), apply these defaults without asking:

• Language: English for subject and body unless the user explicitly requests another language.
• Atomic splitting: group changes by concern and create one commit per group when the changes are unrelated.
• Execution: stage and commit in the same turn; do not stop after proposing messages.
• Attribution: none, of any kind (see Absolute Rules below).
• Detail: detailed multi-paragraph body for non-trivial changes.

Follow Conventional Commits specification with expert-level detail and clarity:

Commit Types

Expert-Level Commit Format

A professional commit message tells a complete story. It should read like technical documentation that future developers (including yourself) will rely on.

<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.>

Subject Line Rules:

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

Body Rules:

• 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

Footer Rules:

• 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

ABSOLUTE RULES (Non-negotiable - VIOLATIONS MUST BE REMOVED):

• 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

Example 1: Simple Refactoring (Minimal Acceptable)

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

Example 2: Feature Implementation

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)

Example 2: Bug Fix

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

Example 3: Refactoring

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

Example 4: Configuration/Build

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

When the user runs /git-commit, /git-skills:commit, asks to commit, or runs 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

1. Plan Atomic Commits

• Group changed files by logical concern
• Create one commit per group when changes are unrelated; keep an implementation with its tests
• Order commits by dependency between groups
• Preserve existing staging when it is already coherent

1. Suggest Type and Scope

• Based on file paths and diff content
• Common scopes: api, ui, auth, db, config, deps
• Choose specific, meaningful scope names

1. 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, written in English by default
• 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