my-vault/.claude/commands/git-commit-msg.md

---
allowed-tools: Bash, AskUserQuestion
description: AI-generated git commit messages from staged changes
argument-hint: [optional: type or scope hint]
---

# AI Git Commit Message Generator

Analyzes your staged git changes and generates a well-structured conventional commit message using AI. Perfect for creating meaningful, consistent commit messages that follow best practices.

## Task

Review staged changes, analyze the modifications, and generate a descriptive conventional commit message that accurately describes what was changed and why.

## Process

### 1. **Check Git Status**

First, verify there are changes to commit:

```bash
git status
```

If no changes are staged, check if there are unstaged changes:
- If yes: Ask user if they want to stage all changes
- If no: Exit with message "No changes to commit"

### 2. **Review Changes**

Show detailed diff of staged changes:

```bash
# Show staged changes
git diff --cached --stat
git diff --cached
```

Also check recent commits for context on commit message style:

```bash
git log --oneline -5
```

### 3. **Analyze Changes**

Examine the diff output to understand:
- **What changed**: Files modified, added, or deleted
- **Scope**: Which modules/components are affected
- **Type**: Is this a feature, fix, refactor, docs, etc.?
- **Impact**: Breaking changes, new functionality, bug fixes
- **Details**: Specific changes worth mentioning

### 4. **Generate Commit Message**

Create a conventional commit message following this format:

```
<type>(<scope>): <short summary>

<detailed description>

<footer>
```

**Type Options:**
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation changes
- `style`: Code style/formatting (no logic change)
- `refactor`: Code restructuring (no feature change)
- `perf`: Performance improvement
- `test`: Adding or updating tests
- `chore`: Build process, dependencies, tooling
- `ci`: CI/CD configuration changes
- `revert`: Reverting previous changes

**Message Structure:**
- **Subject line**: Max 72 characters, imperative mood ("add" not "added")
- **Body** (optional): Explain what and why (not how)
- **Footer** (optional): Breaking changes, issue references

**Example:**
```
feat(auth): add OAuth2 login flow

Implement OAuth2 authentication with Google and GitHub providers.
Users can now log in using their existing accounts, improving
onboarding experience and security.

- Add OAuth2 client configuration
- Create provider-specific callback handlers
- Update login UI with social login buttons
- Add user account linking logic

Closes #123
```

### 5. **Present Options**

Show the generated commit message to the user with options:

```
📝 Generated Commit Message:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[Generated message here]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Options:
1. Use this message (recommended)
2. Edit message
3. Generate alternative version
4. Cancel commit
```

Use AskUserQuestion to get user's choice.

### 6. **Commit Changes**

Based on user selection:

**Option 1 - Use as-is:**
```bash
git commit -m "$(cat <<'EOF'
[Generated message]

🤖 Generated with Claude Code
EOF
)"
```

**Option 2 - Edit:**
- Ask user for modifications
- Show revised message
- Confirm before committing

**Option 3 - Regenerate:**
- Ask for guidance (e.g., "focus more on why", "simpler message")
- Generate new version
- Show options again

**Option 4 - Cancel:**
- Exit without committing
- Changes remain staged

### 7. **Confirm Success**

After committing:
```bash
git log -1 --pretty=format:"%h - %s"
git status
```

Show commit hash and updated status to confirm success.

## Arguments

**Optional user input:**
- Type hint: `fix`, `feat`, `docs`, etc.
- Scope hint: `auth`, `api`, `ui`, etc.
- Custom context: "this fixes the login timeout issue"

## Example Usage

```bash
# Auto-generate from staged changes
/git-commit-msg

# Provide type hint
/git-commit-msg fix

# Provide type and scope
/git-commit-msg "feat(api)"

# Provide context
/git-commit-msg "fixing the auth timeout bug mentioned in #234"
```

## Output Example

```
🔍 Analyzing staged changes...

📊 Changes Summary:
 src/auth/oauth.ts         | 45 +++++++++++++++++++++++++++-
 src/components/Login.tsx  | 23 +++++++++++---
 tests/auth.test.ts        | 18 +++++++++++
 3 files changed, 81 insertions(+), 5 deletions(-)

📝 Generated Commit Message:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
feat(auth): add OAuth2 social login integration

Implement OAuth2 authentication with Google and GitHub providers
to improve user onboarding and security.

- Add OAuth2 client configuration
- Create provider callback handlers
- Update login UI with social buttons
- Add comprehensive auth tests

Closes #234
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ Committed successfully: a7f3b2c
```

## Best Practices

**Subject Line:**
- Use imperative mood: "add" not "added" or "adds"
- Don't end with a period
- Keep under 72 characters
- Be specific but concise

**Body:**
- Explain **what** and **why**, not **how**
- Wrap at 72 characters per line
- Use bullet points for multiple changes
- Reference issues when relevant

**Scope:**
- Use specific module/component names
- Keep consistent with codebase conventions
- Omit if change affects multiple areas

**Common Patterns:**
- `feat(api): add user search endpoint`
- `fix(ui): resolve mobile menu overflow issue`
- `docs(readme): update installation instructions`
- `refactor(auth): simplify token validation logic`
- `perf(db): optimize query performance with indexes`
- `test(api): add integration tests for auth flow`

## Smart Features

**Context Awareness:**
- Learn from existing commit history style
- Detect breaking changes automatically
- Identify issue references in branch names
- Suggest appropriate scope from file paths

**Safety:**
- Show full diff before committing
- Allow message editing
- Confirm before finalizing
- Never auto-push (commit locally only)

**Quality Checks:**
- Validate conventional commit format
- Check subject line length
- Ensure meaningful description
- Verify scope accuracy

## Configuration

Can be customized for your project:
- Custom commit types
- Required/optional scope
- Footer format (issue tracking)
- Additional validation rules

## Integration with Git Plugin

This skill is designed to work seamlessly with Obsidian git plugins:
- Generates messages compatible with all git workflows
- Works with staging area from any git client
- Commits stay in local history until you push
- No changes to your git configuration

## Tips

- **Stage selectively**: Use `git add -p` for partial file commits
- **Commit atomically**: One logical change per commit
- **Reference issues**: Use "Closes #123" in footer
- **Breaking changes**: Start body with "BREAKING CHANGE:"
- **Co-authors**: Add in footer: `Co-authored-by: Name <email>`

## Troubleshooting

**"No changes staged":**
- Run `git add <files>` first, or let skill stage changes for you

**"Generated message too generic":**
- Select "Generate alternative" and provide more context
- Check that changes have meaningful diffs

**"Wrong commit type detected":**
- Provide type hint as argument: `/git-commit-msg fix`

**"Commit message too long":**
- Skill will automatically wrap at 72 characters
- Complex changes will use multi-line body

## Advanced Usage

**Multi-file changes:**
```bash
# Skill will group related changes and create comprehensive message
git add src/auth/*.ts src/components/Login.tsx
/git-commit-msg
```

**Partial commits:**
```bash
# Stage specific hunks
git add -p src/complex-file.ts
/git-commit-msg "focusing on the bug fix part"
```

**Amending commits:**
```bash
# After running the skill, if you need to amend:
git commit --amend
# Edit the AI-generated message as needed
```

---

**Pro tip**: Use this skill consistently to build a clean, professional git history that makes code review and debugging much easier!