/atomic

Atomic Commit Creator

Intelligently groups changes into atomic commits based on feature analysis. Each commit includes related implementation files, tests, and documentation.

Arguments Provided

$ARGUMENTS

Overview

This command operates in three phases:

1. Assessment - Analyze all changes and identify distinct features
2. Build Commit List - Map files and file segments to each feature
3. Add and Commit - Create atomic commits with proper formatting

Important Rules

• Stop immediately if any git command fails
• If any new files look related to planning or Claude testing (not unit tests associated with features, but test files generated by Claude for validation), leave them unless they're the only uncommitted changes
• Each commit should represent ONE logical change
• Documentation changes that describe code changes must be committed together with those code changes
• Generated/auto-updated files should be committed with appropriate attribution

Instructions

Phase 1: Assessment

1. Gather git status information:

   git status
   

2. Check for uncommitted changes:

   git diff
   git diff --staged
   

3. Identify files that should be excluded:

   • Look for files that appear to be Claude-generated planning or testing files
   • Common patterns: *-test-*.md, *-plan.md, *-scratch.*, temporary test scripts
   • Check file modification times and content to confirm
   • Only exclude if there are other substantive changes
   • If these planning/testing files are the only changes, include them

4. Analyze changes to identify distinct features:

   • Read all changed files (or representative sections if too large for context window)
   • Look for:
     • New features/functionality
     • Bug fixes
     • Refactoring
     • Test additions/modifications
     • Configuration changes
     • Generated file updates (proto, codegen, etc.)
     • Documentation changes (note: these should be grouped WITH the code/feature they document, not as separate commits)
   • Group related changes together even if they span multiple files
   • For files with multiple unrelated changes, note which parts belong to which feature

5. Create a TodoWrite task list of detected features:

   • Each todo should be: "Commit [feature name]"
   • Example format:
     • "Commit OAuth authentication middleware"
     • "Commit user database schema"
     • "Commit authentication API endpoints"
     • "Commit protobuf definition updates"

6. Handle arguments if provided:

   • If $ARGUMENTS contains a feature name, focus ONLY on that feature
   • If a rationale is also provided in arguments, note it for later use
   • If only committing one feature, still assess all features but only proceed with the specified one

Phase 2: Build Commit List for Each Feature

For each feature identified (or the single feature if specified in arguments):

1. Map all related files:

   • List implementation files
   • List test files (unit tests, integration tests)
   • List documentation files that document this feature (must be included with the feature)
   • List configuration files
   • List generated files (if applicable)

2. Handle files with mixed changes:

   • If a file contains changes for multiple features, note which lines/hunks belong to which feature
   • Use the git-partial-commit skill to stage only relevant changes (see instructions below in Phase 3)
   • Document which parts of the file are being staged

3. Verify completeness:

   • Ensure each feature has all its related pieces
   • Check that no orphaned changes are left unstaged
   • Confirm tests and documentation for the feature are included with the feature

4. Determine commit type and scope:

   • Type: feat, fix, refactor, docs, test, chore, style, perf
   • Scope: The component/module affected (e.g., "auth", "database", "api")
   • Choose the most specific scope that accurately describes the change

5. Gather or confirm rationale:

   • If rationale was provided in arguments, use it
   • If the rationale is clear from recent context/conversation, infer it
   • If rationale is not in context window and not provided, ask the user:
     • Use AskUserQuestion tool
     • "What was the rationale for [feature name]?"
     • Provide context about what the feature does to help them respond

Phase 3: Add and Commit Files

For each feature (updating TodoWrite status as you go):

1. Stage files for this commit:

   For files wholly belonging to this feature:

   git add <file1> <file2> <file3>
   

   For files with partial changes (mixed features in one file):

   Use the git-partial-commit skill to stage only the lines/hunks belonging to this feature:

   a. Get the full diff of the file:

   git diff --unified=5 <file>
   

   b. Construct a patch containing only the hunks for this feature. The patch must follow unified diff format:

   diff --git a/<file> b/<file>
   index <old-hash>..<new-hash> <mode>
   --- a/<file>
   +++ b/<file>
   @@ -<old-start>,<old-count> +<new-start>,<new-count> @@
   <context lines and changes for this feature only>
   

   c. Stage the partial changes using the helper script:

   ${CLAUDE_PLUGIN_ROOT}/skills/git/partial-commit/stage-lines.sh <file> "$(cat <<'EOF'
   <paste the constructed patch here>
   EOF
   )"
   

   Verify what's staged:

   git diff --cached
   

2. Generate commit message:

   Follow this exact format:

   <type>(<scope>): <brief description>
   
   - <bullet point explaining what changed>
   - <bullet point explaining why it changed>
   - <bullet point for each major modification>
   - <bullet point for any breaking changes or deprecations>
   - <bullet point for generated/auto-updated files if relevant>
   
   Rationale: <paragraph description of the reason for the change>
   

   Commit types:

   • feat: New features
   • fix: Bug fixes
   • refactor: Code restructuring without functionality change
   • docs: Documentation changes
   • test: Test additions/modifications
   • chore: Build, dependencies, generated files
   • style: Formatting, whitespace
   • perf: Performance improvements

   Example:

   feat(auth): Add OAuth2 authentication middleware
   
   - Add OAuth2 provider configuration and client setup
   - Implement middleware for token validation and user session creation
   - Add error handling for expired and invalid tokens
   - Integrate with existing user repository for account lookup
   
   Rationale: Users requested the ability to authenticate using their existing OAuth2 providers (Google, GitHub) instead of creating new credentials. This reduces friction in the onboarding process and improves security by leveraging established identity providers.
   
   This commit made by [/tal:git:commit:atomic](https://github.com/tal/plugin-marketplace/tree/main/plugins/tal/commands/git/commit/atomic.md)
   

3. Create the commit using heredoc:

   git commit -m "$(cat <<'EOF'
   <type>(<scope>): <brief description>
   
   - <bullet point 1>
   - <bullet point 2>
   - <bullet point 3>
   
   Rationale: <rationale paragraph>
   
   This commit made by [/tal:git:commit:atomic](https://github.com/tal/plugin-marketplace/tree/main/plugins/tal/commands/git/commit/atomic.md)
   EOF
   )"
   

4. Check for errors:

   • If the commit fails, STOP IMMEDIATELY
   • Report the error to the user
   • Do not proceed with additional commits
   • Ask the user how to resolve the issue

5. Verify the commit:

   git log -1 --stat
   

6. Update todo status:

   • Mark the feature commit as completed
   • Move to the next feature

Final Steps

After all commits are created:

1. Show summary:

   git log --oneline -n <number-of-commits-created>
   

2. Check for remaining unstaged changes:

   git status
   

3. Report to user:

   • List all commits created
   • Note any files that were excluded (Claude testing/planning files)
   • Mention any remaining uncommitted changes
   • Remind user they can push when ready

Example Atomic Commits

Instead of:

feat: Add user authentication system with OAuth and database schema

Prefer multiple atomic commits:

1. feat(auth): Add OAuth configuration and middleware (includes related docs)
2. feat(database): Add user authentication schema and migrations (includes related docs)
3. feat(api): Add authentication endpoints and validation (includes related docs)
4. chore(proto): Update user service protobuf definitions
5. chore(generated): Regenerate protobuf bindings for user service

Note: Each commit includes its related documentation (e.g., README updates, inline docs, CLAUDE.md sections). Documentation changes are NOT separated into standalone docs: commits unless they are purely documentation improvements unrelated to code changes.

Commit Message Quality Checklist

Before each commit, verify:

• Commit message is descriptive and follows format
• Only related files are staged
• Commit represents one logical change
• Generated files are properly attributed with 'chore' type
• Tests for the feature are included
• Documentation is included if relevant
• Rationale clearly explains the "why"

Key Principles

• Clarity over convenience - Multiple small, focused commits are better than one large commit
• Atomic means complete - Each commit should include everything needed for that feature to work
• Logical grouping - Related changes stay together even across files
• Stop on error - Never continue if a git command fails
• Context awareness - Consider the full scope of changes before deciding how to group them

---

Now proceed with these three phases. Remember to stop immediately if any git command fails.