Initial commit
This commit is contained in:
Zhongwei Li
323
commands/commit.md
Normal file
323
commands/commit.md
Normal file
@@ -0,0 +1,323 @@
|
||||
---
|
||||
name: git:commit
|
||||
description: Git conventions and workflow guidelines using Conventional Commits
|
||||
---
|
||||
|
||||
# Git Conventions and Workflow Guidelines
|
||||
|
||||
Guide Claude Code through creating properly formatted commit messages and following git best practices using Conventional Commits specification.
|
||||
|
||||
## Command
|
||||
|
||||
`/git:commit [type] [scope] [description]`
|
||||
|
||||
## Arguments
|
||||
|
||||
- `$1`: type - `feat|fix|docs|style|refactor|perf|test|chore|ci` (optional, interactive if not provided)
|
||||
- `$2`: scope - Component or module name (optional)
|
||||
- `$3`: description - Brief description in imperative mood (optional)
|
||||
|
||||
## Slash Command Usage Examples
|
||||
|
||||
### Interactive Mode (Recommended)
|
||||
|
||||
```bash
|
||||
/git:commit
|
||||
```
|
||||
|
||||
**What happens:**
|
||||
1. Claude analyzes staged changes using `git diff --cached`
|
||||
2. Asks you what type of change this is (feat, fix, docs, etc.)
|
||||
3. Asks for the scope (optional)
|
||||
4. Asks for a description or suggests one based on the changes
|
||||
5. Generates a properly formatted commit message
|
||||
6. Shows you the message and asks for confirmation
|
||||
7. Creates the commit with the approved message
|
||||
|
||||
### Quick Mode with Arguments
|
||||
|
||||
```bash
|
||||
# Feature with scope
|
||||
/git:commit feat auth "add JWT authentication"
|
||||
|
||||
# Bug fix without scope
|
||||
/git:commit fix "handle null response from server"
|
||||
|
||||
# Documentation update
|
||||
/git:commit docs readme "update installation steps"
|
||||
|
||||
# Refactoring with scope
|
||||
/git:commit refactor database "optimize query performance"
|
||||
```
|
||||
|
||||
### Common Usage Patterns
|
||||
|
||||
```bash
|
||||
# Let Claude analyze changes and suggest commit message
|
||||
/git:commit
|
||||
|
||||
# Specify type, Claude suggests scope and description
|
||||
/git:commit feat
|
||||
|
||||
# Specify type and scope, Claude suggests description
|
||||
/git:commit fix api
|
||||
```
|
||||
|
||||
## When to Use This Command
|
||||
|
||||
- Before committing changes to ensure proper message format
|
||||
- When you want Claude to analyze your changes and suggest appropriate commit type
|
||||
- When you need help writing clear, conventional commit messages
|
||||
- When working on a project that requires Conventional Commits
|
||||
- As a learning tool to understand Conventional Commits format
|
||||
|
||||
## Language Requirements
|
||||
|
||||
All git-related text MUST be written in English:
|
||||
|
||||
- Commit messages
|
||||
- Branch names
|
||||
- Pull request titles and descriptions
|
||||
- Code review comments
|
||||
- Issue titles and descriptions
|
||||
|
||||
## Commit Message Format
|
||||
|
||||
All commit messages MUST follow the [Conventional Commits](mdc:https:/www.conventionalcommits.org) specification:
|
||||
|
||||
```
|
||||
<type>[optional scope]: <description>
|
||||
|
||||
[optional body]
|
||||
|
||||
[optional footer(s)]
|
||||
```
|
||||
|
||||
### Types
|
||||
|
||||
- `feat`: A new feature
|
||||
- `fix`: A bug fix
|
||||
- `docs`: Documentation only changes
|
||||
- `style`: Changes that do not affect the meaning of the code (formatting, etc)
|
||||
- `refactor`: A code change that neither fixes a bug nor adds a feature
|
||||
- `perf`: A code change that improves performance
|
||||
- `test`: Adding missing tests or correcting existing tests
|
||||
- `chore`: Changes to the build process or auxiliary tools
|
||||
- `ci`: Changes to CI configuration files and scripts
|
||||
|
||||
### Scope
|
||||
|
||||
The scope should be the name of the component affected (as perceived by the person reading the changelog).
|
||||
|
||||
Examples:
|
||||
|
||||
- `feat(auth): add login with Google`
|
||||
- `fix(api): handle null response from server`
|
||||
- `docs(readme): update installation steps`
|
||||
|
||||
### Description
|
||||
|
||||
- Use the imperative, present tense: "change" not "changed" nor "changes"
|
||||
- Don't capitalize first letter
|
||||
- No dot (.) at the end
|
||||
- Write in english
|
||||
|
||||
## Branch Naming Convention
|
||||
|
||||
Branches should follow this pattern:
|
||||
|
||||
```
|
||||
<type>/<short-description>
|
||||
```
|
||||
|
||||
For features and fixes that are tracked in a project management system, include the ticket number:
|
||||
|
||||
```
|
||||
<type>/<ticket-number>-<short-description>
|
||||
```
|
||||
|
||||
Examples:
|
||||
|
||||
- `feat/add-google-auth`
|
||||
- `fix/handle-null-responses`
|
||||
- `docs/update-readme`
|
||||
- `feat/PROJ-123-add-google-auth`
|
||||
- `fix/PROJ-456-handle-null-responses`
|
||||
|
||||
## Workflow Guidelines
|
||||
|
||||
1. **Protected Branches**
|
||||
|
||||
- `main` (or `master`): Production-ready code, protected branch
|
||||
- Direct commits to protected branches are NOT allowed
|
||||
- All changes must come through Pull Requests
|
||||
|
||||
2. **Feature Development**
|
||||
|
||||
```bash
|
||||
# First, check if you're on a protected branch
|
||||
git branch --show-current
|
||||
|
||||
# If on main/master, create and checkout a new feature branch
|
||||
git checkout -b feat/my-new-feature main
|
||||
|
||||
# Make changes and commit
|
||||
git add .
|
||||
git commit -m "feat(scope): add new feature"
|
||||
|
||||
# Keep branch updated with main
|
||||
git fetch origin main
|
||||
git rebase origin/main
|
||||
|
||||
# Push changes
|
||||
git push origin feat/my-new-feature
|
||||
```
|
||||
|
||||
3. **Pull Request Process**
|
||||
|
||||
- Create PR from feature branch to main/master
|
||||
- Use PR template if available
|
||||
- Request at least 2 code reviews
|
||||
- All tests must pass
|
||||
- No merge conflicts
|
||||
- Squash commits when merging
|
||||
|
||||
4. **Release Process**
|
||||
|
||||
```bash
|
||||
# Create release branch from main
|
||||
git checkout main
|
||||
git pull origin main
|
||||
git checkout -b release/v1.0.0
|
||||
|
||||
# After testing, merge back to main via PR
|
||||
# After PR is approved and merged:
|
||||
git checkout main
|
||||
git pull origin main
|
||||
git tag -a v1.0.0 -m "version 1.0.0"
|
||||
git push origin main --tags
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
✅ Good Commits:
|
||||
|
||||
```bash
|
||||
feat(auth): implement JWT authentication
|
||||
fix(api): handle edge case in user validation
|
||||
docs(api): update API documentation
|
||||
style(components): format according to style guide
|
||||
refactor(database): optimize query performance
|
||||
test(auth): add unit tests for login flow
|
||||
```
|
||||
|
||||
❌ Bad Commits:
|
||||
|
||||
```bash
|
||||
Fixed stuff
|
||||
Updated code
|
||||
WIP
|
||||
Quick fix
|
||||
```
|
||||
|
||||
## Implementation Workflow
|
||||
|
||||
When `/git:commit` is invoked, follow these steps:
|
||||
|
||||
### Step 1: Analyze Current State
|
||||
|
||||
1. **Check for staged changes:**
|
||||
```bash
|
||||
git diff --cached --stat
|
||||
```
|
||||
- If no staged changes, inform user and suggest: `git add <files>`
|
||||
- Show summary of what will be committed
|
||||
|
||||
2. **Check current branch:**
|
||||
```bash
|
||||
git branch --show-current
|
||||
```
|
||||
- If on protected branch (main/master), warn user strongly
|
||||
- Suggest creating a feature branch instead
|
||||
|
||||
### Step 2: Determine Commit Type
|
||||
|
||||
If type not provided as argument:
|
||||
|
||||
1. Analyze the changes with `git diff --cached`
|
||||
2. Categorize based on file types and changes:
|
||||
- New files in `/features/`, new functions → likely `feat`
|
||||
- Changes in test files → likely `test`
|
||||
- Changes in README, docs/ → likely `docs`
|
||||
- Bug fixes, error handling → likely `fix`
|
||||
- Code cleanup, no behavior change → likely `refactor`
|
||||
3. Suggest the most appropriate type to user
|
||||
4. Ask user to confirm or choose different type
|
||||
|
||||
### Step 3: Determine Scope
|
||||
|
||||
If scope not provided:
|
||||
|
||||
1. Look at file paths to identify component/module
|
||||
2. Common patterns:
|
||||
- `src/auth/*` → scope: `auth`
|
||||
- `src/api/*` → scope: `api`
|
||||
- `docs/*` → scope: `docs` or specific doc name
|
||||
- Multiple components → ask user or use general scope
|
||||
3. Suggest scope or ask user
|
||||
4. Scope is optional - allow user to skip
|
||||
|
||||
### Step 4: Create Description
|
||||
|
||||
If description not provided:
|
||||
|
||||
1. Analyze `git diff --cached` for key changes
|
||||
2. Generate 2-3 description suggestions following rules:
|
||||
- Use imperative mood ("add" not "added" or "adds")
|
||||
- Start with lowercase
|
||||
- No period at end
|
||||
- Be specific but concise (max 50 chars for subject)
|
||||
3. Present suggestions to user
|
||||
4. Allow user to choose or provide their own
|
||||
|
||||
### Step 5: Build Complete Message
|
||||
|
||||
1. Format as: `<type>(<scope>): <description>`
|
||||
2. If changes are complex, ask if user wants to add body
|
||||
3. For breaking changes, remind about `BREAKING CHANGE:` footer
|
||||
4. Show complete formatted message to user
|
||||
|
||||
### Step 6: Commit with Message
|
||||
|
||||
1. Show the final commit command:
|
||||
```bash
|
||||
git commit -m "type(scope): description"
|
||||
```
|
||||
2. Ask for confirmation
|
||||
3. Execute the commit
|
||||
4. Show commit hash and summary
|
||||
5. Remind about push if needed: `git push origin <branch>`
|
||||
|
||||
### Step 7: Additional Guidance
|
||||
|
||||
After successful commit:
|
||||
- Remind about related commits that should be squashed
|
||||
- Suggest creating PR if feature is complete
|
||||
- Remind about conventional commit benefits for changelog generation
|
||||
|
||||
## Pre-commit Hooks
|
||||
|
||||
Consider using pre-commit hooks to enforce these conventions:
|
||||
|
||||
- Commit message format validation
|
||||
- Code linting
|
||||
- Test execution
|
||||
- Branch naming validation
|
||||
- Protected branch validation
|
||||
|
||||
## Additional Notes
|
||||
|
||||
Avoid adding Claude as a co-author, while I understand that Claude wants recognition it's not always accurate that
|
||||
Claude has in any way contributed as a co-author beyond writing the commit message that this command is used for. If
|
||||
it's felt that Claude deserves to be listed as a co-author in the commit message it should be presented as an option
|
||||
before adding.
|
||||
Reference in New Issue
Block a user