Commit

Git Commit Skill

Create commits following STAR project conventions with proper safety checks and commit message formatting.

Git Safety Protocol

NEVER:

• Update git config without user permission
• Run destructive commands (push --force, reset --hard, checkout ., restore ., clean -f, branch -D) unless explicitly requested
• Skip hooks (--no-verify, --no-gpg-sign) unless explicitly requested
• Force push to main/master (warn user if requested)
• CRITICAL: Amend commits when pre-commit hooks fail - the commit did NOT happen, so --amend would modify the PREVIOUS commit!
• Commit changes unless explicitly asked (only commit when user requests it)
• Use git add -A or git add . (prefer adding specific files by name to avoid accidentally staging sensitive files)

ALWAYS:

• Create NEW commits rather than amending (unless user explicitly requests git commit --amend)
• When pre-commit hook fails: fix the issue, re-stage, and create a NEW commit
• Add specific files by name rather than using git add -A
• Avoid committing sensitive files (.env, credentials.json, etc.)

Commit Workflow

When the user asks to create a commit, follow these steps:

Step 1: Analyze Current State [PASS] READ-ONLY (Safe to run immediately)

Run these commands in parallel to understand the repository state:

# See all untracked files (NEVER use -uall flag)
git status

# See both staged and unstaged changes
git diff HEAD

# See recent commit messages to match style
git log --oneline -n 10

Step 2: Draft Commit Message [PASS] READ-ONLY (Safe to draft)

Analyze all changes (both previously staged and newly added) and draft a message that:

• Summarizes the nature of changes (new feature, enhancement, bug fix, refactoring, test, docs)
• Is concise (1-2 sentences)
• Focuses on "why" rather than "what"
• Follows the project's commit message style (check recent commits)
• Uses accurate verbs:
  • "add" = wholly new feature
  • "update" = enhancement to existing feature
  • "fix" = bug fix
  • "refactor" = code restructuring

IMPORTANT: Do NOT add AI attribution. Never include "Co-Authored-By: Claude" or "Generated by Claude Code" footers. Write natural, human-style commit messages.

Step 3: Stage and Commit

Run sequentially:

# Add relevant files by name (NOT git add -A or git add .)
git add path/to/file1.c path/to/file2.h

# Create commit with proper message formatting
git commit -m "$(cat <<'EOF'
Your commit message here.

Additional details if needed (optional).
EOF
)"

# Verify commit succeeded
git status

Note: Use HEREDOC format for commit messages to ensure proper formatting and avoid shell escaping issues.

Step 4: Handle Pre-commit Hook Failures

If pre-commit hook fails:

1. DO NOT use --amend - the commit did NOT happen yet!
2. Fix the issue identified by the hook
3. Re-stage the fixed files: git add path/to/fixed/file
4. Create a NEW commit (not amend)

Examples

Example 1: Simple Feature Addition

# Step 1: Check status (READ-ONLY)
git status
git diff HEAD
git log --oneline -n 10

# Step 2: Draft message (READ-ONLY)
# Message: "Add PID controller implementation"
# Details: "Implements discrete-time PID algorithm with anti-windup and derivative filtering for motor velocity control."

# Step 3: Stage and commit
git add src/rx_pid.c src/rx_pid.h

git commit -m "$(cat <<'EOF'
Add PID controller implementation

Implements discrete-time PID algorithm with anti-windup and
derivative filtering for motor velocity control.
EOF
)"

# Step 4: Verify
git status

Example 2: Bug Fix

git add src/rx_spi.c

git commit -m "$(cat <<'EOF'
Fix SPI timeout handling

Corrects timeout calculation to use milliseconds instead of
microseconds, preventing premature timeouts.
EOF
)"

git status

Example 3: Documentation Update

git add CLAUDE.md
git commit -m "Update CLAUDE.md with LSP configuration instructions"

Common Mistakes to Avoid

[FAIL] Wrong: Using git add . (might stage sensitive files) [PASS] Correct: git add src/module.c include/module.h

[FAIL] Wrong: Amending after hook failure [PASS] Correct: Fix issue, re-stage, create NEW commit

[FAIL] Wrong: Adding AI attribution to commit message [PASS] Correct: Write natural, human-style commit messages

[FAIL] Wrong: Vague messages like "fix bug" or "update code" [PASS] Correct: "Fix SPI timeout calculation in rx_spi.c"

Important Notes

• No -uall flag: Never use git status -uall (can cause memory issues on large repos)
• Sensitive files: Never commit .env, credentials.json, API keys, or similar
• Commit when asked: Only create commits when user explicitly requests them
• Natural messages: No AI attribution, no "Generated by..." footers
• Specific staging: Prefer git add <specific files> over git add .

Converted and distributed by TomeVault — claim your Tome and manage your conversions.