prulloac Git Commit Workflow
Overview
This skill provides a structured workflow for committing git changes that respects repository-specific guidelines and falls back to conventional commits when no guidelines exist. It ensures commits are logical, well-grouped, and follow established standards.
Workflow
Follow these steps to commit changes:
1. Read Repository Guidelines
- Look for CONTRIBUTING, CONTRIBUTING.md, or similar files in the repository root
- Extract commit message standards, guidelines, and any specific requirements
- If no guidelines found, prepare to use conventional commits as fallback
2. Assess Current Changes
- Run
git statusto see all modified, added, and untracked files - Note staged vs unstaged changes
3. Analyze Changes in Detail
- Run
git diff(andgit diff --stagedif needed) to understand what changes were made - Review the nature of changes: bug fixes, features, refactoring, documentation, etc.
4. Group Related Changes
- Logically group files by related changes
- See references/grouping_changes.md for guidance on grouping strategies
- Avoid mixing unrelated changes in the same commit
5. Perform Commits
- If CONTRIBUTING guidelines exist, follow their commit message format and grouping requirements
- If no guidelines, use conventional commits standard: See references/conventional_commits.md
- Stage appropriate files for each commit
- Write descriptive commit messages
- Run
git commitwith proper messages
Resources
references/
grouping_changes.md: Guidance on how to group related file changes into logical commitsconventional_commits.md: Reference for conventional commits specification
Quick Reference: Conventional Commit Format
<type>(<scope>): <subject>
<body>
<footer>
Common types:
feat: A new featurefix: A bug fixrefactor: Code change that neither fixes a bug nor adds a featuredocs: Documentation-only changestest: Adding tests or updating test logicperf: Code change that improves performanceci: CI/CD configuration changeschore: Changes to build scripts, dependencies, or other non-source changes
Examples:
feat(api): add user authentication endpointsfix(validation): handle null values in validation utilitydocs: update installation instructionsrefactor: simplify button component styling
Concrete Examples
Example 1: Multi-Step Commit with Conventional Format
Initial Repository State:
$ git status
On branch main
Your branch is ahead of 'origin/main' by 0 commits.
Changes not staged for commit:
modified: src/auth/login.ts
modified: src/auth/logout.ts
modified: tests/auth.test.ts
modified: docs/README.md
modified: .gitignore
Untracked files:
src/auth/middleware.ts
Step 1: Analyze Changes
$ git diff src/auth/login.ts
- Added password validation
- Added JWT token generation
- Added error handling
$ git diff src/auth/logout.ts
- Added token cleanup
- Added session invalidation
$ git diff tests/auth.test.ts
- Added tests for login validation
- Added tests for logout flow
$ git diff docs/README.md
- Updated authentication section
- Added examples
$ git diff .gitignore
- Added .env.local to ignore rules
Step 2: Group Related Changes
Group 1 (Feature: Authentication):
- src/auth/login.ts
- src/auth/logout.ts
- src/auth/middleware.ts
Group 2 (Tests):
- tests/auth.test.ts
Group 3 (Documentation):
- docs/README.md
Group 4 (Configuration):
- .gitignore
Step 3-4: Create Commits
$ git add src/auth/login.ts src/auth/logout.ts src/auth/middleware.ts
$ git commit -m "feat(auth): implement user login and logout endpoints
- Add password validation with bcrypt hashing
- Implement JWT token generation and refresh
- Add logout handler for session cleanup
- Include middleware for authentication checks
- Improve error handling with specific error codes"
[main a1b2c3d] feat(auth): implement user login and logout endpoints
3 files changed, 245 insertions(+), 12 deletions(-)
$ git add tests/auth.test.ts
$ git commit -m "test(auth): add comprehensive authentication tests
- Add tests for login validation
- Add tests for password requirements
- Add tests for JWT token generation
- Add tests for logout flow and cleanup
- Achieve 95% coverage for auth module"
[main d4e5f6g] test(auth): add comprehensive authentication tests
1 file changed, 189 insertions(+)
$ git add docs/README.md
$ git commit -m "docs: update authentication documentation
- Add authentication setup guide
- Include usage examples for login endpoint
- Update API reference section
- Add troubleshooting for common auth errors"
[main h7i8j9k] docs: update authentication documentation
1 file changed, 67 insertions(+)
$ git add .gitignore
$ git commit -m "chore: update .gitignore for environment files
- Add .env.local to ignore rules
- Add .env.*.local pattern for local overrides"
[main l0m1n2o] chore: update .gitignore for environment files
1 file changed, 3 insertions(+)
Final Result:
$ git log --oneline -4
l0m1n2o chore: update .gitignore for environment files
h7i8j9k docs: update authentication documentation
d4e5f6g test(auth): add comprehensive authentication tests
a1b2c3d feat(auth): implement user login and logout endpoints
$ git status
On branch main
Your branch is ahead of 'origin/main' by 4 commits.
(use "git push" to publish your local commits)
nothing to commit, working tree clean
Example 2: Bug Fix with Related Test Update
Initial State:
$ git status
On branch main
Changes not staged for commit:
modified: src/utils/date-parser.ts
modified: tests/utils/date-parser.test.ts
$ git diff src/utils/date-parser.ts
- Fixed timezone handling for UTC offsets
- Fixed leap year calculation
- Added validation for invalid dates
Commit Process:
$ git add src/utils/date-parser.ts tests/utils/date-parser.test.ts
$ git commit -m "fix(utils): correct date parsing for timezone offsets
- Fix UTC offset parsing to correctly handle +/-HH:MM format
- Fix leap year calculation for years divisible by 400
- Add validation to reject invalid date strings
- Update tests with edge cases for timezone handling
- Fixes issue #456: Date parsing fails with +05:30 timezone"
[main p3q4r5s] fix(utils): correct date parsing for timezone offsets
2 files changed, 45 insertions(+), 8 deletions(-)
Output Summary:
✅ COMMIT SUCCESSFUL
Commit: p3q4r5s
Type: fix (Bug Fix)
Scope: utils
Subject: correct date parsing for timezone offsets
Files Changed: 2
- src/utils/date-parser.ts (45 +, 8 -)
- tests/utils/date-parser.test.ts (8 +, 2 -)
Files Staged: 2/2
Working Directory: Clean
Example 3: Refactoring with Multiple Files
Initial State:
$ git status
On branch main
Changes not staged for commit:
modified: src/components/Button.tsx
modified: src/components/Form.tsx
modified: src/styles/colors.css
modified: tests/components/Button.test.tsx
modified: tests/components/Form.test.tsx
$ git diff --stat
src/components/Button.tsx | 42 ++++++++++++++
src/components/Form.tsx | 38 ++++++------
src/styles/colors.css | 15 +++--
tests/components/Button.test.tsx | 22 +++++++
tests/components/Form.test.tsx | 18 +++---
Commit Process:
$ git add src/components/Button.tsx src/components/Form.tsx src/styles/colors.css
$ git commit -m "refactor: extract shared styling logic to utility functions
- Extract color constants to dedicated CSS module
- Simplify Button component styling with utility functions
- Reduce CSS duplication in Form component
- Improve maintainability and theme customization
- Maintains 100% backward compatibility"
[main t6u7v8w] refactor: extract shared styling logic to utility functions
3 files changed, 95 insertions(+)
$ git add tests/components/Button.test.tsx tests/components/Form.test.tsx
$ git commit -m "test(components): update tests after styling refactor
- Update Button component tests for new structure
- Update Form component tests for utility functions
- Add tests for color utility functions
- Maintain 100% code coverage"
[main x9y0z1a] test(components): update tests after styling refactor
2 files changed, 40 insertions(+)
Commit History View:
$ git log --oneline -2
x9y0z1a test(components): update tests after styling refactor
t6u7v8w refactor: extract shared styling logic to utility functions
$ git log --graph --oneline --all -5
* x9y0z1a test(components): update tests after styling refactor
* t6u7v8w refactor: extract shared styling logic to utility functions
* d4e5f6g Previous commit
* ...
Validation Checklist
After creating commits, verify:
- ✅ All changes are committed (working tree is clean)
- ✅ Each commit has a single, logical purpose
- ✅ Commit messages follow the repository's guidelines (or conventional commits)
- ✅ Related files are grouped together in commits
- ✅ No unrelated changes are mixed in the same commit
- ✅ Commit messages are clear and descriptive
- ✅ Commit history is logical and easy to understand
- ✅ No sensitive information (keys, passwords) in commits