commit

Overview

Creating clean, atomic commits that follow best practices for version control hygiene. The core principle is one logical change per commit - each commit should represent a single, coherent, easily revertable modification that can stand alone.

User Instructions

Follow any user instructions below. They override the standard workflow when conflicts arise.

<user_instructions> $ARGUMENTS </user_instructions>

Workflow

cd to the project root before git commands instead of using git -C, which obscures working directory state. Execute git commands directly without explanatory preamble. Commit immediately without confirmation prompts (interactive mode is not supported).

1. Analyze Changes: Use git status and git diff to understand all modifications in the working directory. Categorize changes by:

   • STRUCTURAL: Code reorganization, renaming, refactoring without behavior changes
   • BEHAVIORAL: New features, bug fixes, functionality changes
   • DOCUMENTATION: README updates, comment changes, documentation files
   • CONFIGURATION: Build files, dependencies, environment settings

2. Group Logically: Organize changes into logical units where each unit:

   • Addresses a single purpose or problem
   • Structure changes to be atomic and easily revertable for safe rollback
   • Would make sense to revert as a unit

3. Stage Changes: Use appropriate staging strategy:

   • Whole file: git add <file>
   • Hunk-by-hunk: git diff <file> > /tmp/patch.diff, edit the patch to keep only specific hunks, then git apply --cached /tmp/patch.diff
   • To unstage, use git restore --staged (not git reset --hard, which discards work)
   • Fallback: If git apply --cached fails (malformed patch), stage the whole file with git add <file> instead

4. Handle Pre-commit Hooks: If hooks complain about unstaged changes:

   • Stash unstaged changes first: git stash push -p -m "temp: unstaged changes" (select hunks to stash)
   • Or stash all unstaged: git stash push --keep-index -m "temp: unstaged changes"
   • Commit, then restore: git stash pop
   • If hooks modify staged files (auto-formatting), re-add the modified files and retry the commit

5. Create Atomic Commits: For each logical group:

   • Write clear, descriptive commit messages following conventional format
   • Keep first line under 72 characters
   • Include context in body when necessary
   • Commit the working tree state as-is — the user may have made manual edits outside this conversation
   • Use git commit -m "message" directly — never use $() or heredoc subshells in git commands, as they break allowed-tools pattern matching

Attribution

Include a Co-Authored-By footer in every commit message:

If you're an Anthropic Claude model:

Co-Authored-By: Claude <noreply@anthropic.com>

If you're a Google Gemini model:

Co-Authored-By: Gemini <gemini-code-assistant@google.com>

Skip if you're not one of the above models.