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 status to see all modified, added, and untracked files
Note staged vs unstaged changes

3. Analyze Changes in Detail

Run git diff (and git diff --staged if 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 commit with proper messages

Resources

references/

grouping_changes.md: Guidance on how to group related file changes into logical commits
conventional_commits.md: Reference for conventional commits specification

Quick Reference: Conventional Commit Format

<type>(<scope>): <subject>

<body>

<footer>

Common types:

feat: A new feature
fix: A bug fix
refactor: Code change that neither fixes a bug nor adds a feature
docs: Documentation-only changes
test: Adding tests or updating test logic
perf: Code change that improves performance
ci: CI/CD configuration changes
chore: Changes to build scripts, dependencies, or other non-source changes

Examples:

feat(api): add user authentication endpoints
fix(validation): handle null values in validation utility
docs: update installation instructions
refactor: 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

Git Commit Workflow

Overview

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 status to see all modified, added, and untracked files
Note staged vs unstaged changes

3. Analyze Changes in Detail

Run git diff (and git diff --staged if 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 commit with proper messages

Resources

references/

grouping_changes.md: Guidance on how to group related file changes into logical commits
conventional_commits.md: Reference for conventional commits specification

Quick Reference: Conventional Commit Format

<type>(<scope>): <subject>

<body>

<footer>

Common types:

feat: A new feature
fix: A bug fix
refactor: Code change that neither fixes a bug nor adds a feature
docs: Documentation-only changes
test: Adding tests or updating test logic
perf: Code change that improves performance
ci: CI/CD configuration changes
chore: Changes to build scripts, dependencies, or other non-source changes

Examples:

feat(api): add user authentication endpoints
fix(validation): handle null values in validation utility
docs: update installation instructions
refactor: 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

Adoption

prulloac/git-commit-workflow

$ install --global

Security Scan Results

SKILL.md

Git Commit Workflow

Overview

Workflow

1. Read Repository Guidelines

2. Assess Current Changes

3. Analyze Changes in Detail

4. Group Related Changes

5. Perform Commits

Resources

references/

Quick Reference: Conventional Commit Format

Concrete Examples

Example 1: Multi-Step Commit with Conventional Format

Example 2: Bug Fix with Related Test Update

Example 3: Refactoring with Multiple Files

Validation Checklist

Related Skills

prulloac/vscode-extension-builder

prulloac/system-prompt-validator

prulloac/skill-validator

prulloac/skill-creator

prulloac/git-commit-workflow

$ install --global

Security Scan Results

SKILL.md

Git Commit Workflow

Overview

Workflow

1. Read Repository Guidelines

2. Assess Current Changes

3. Analyze Changes in Detail

4. Group Related Changes

5. Perform Commits

Resources

references/

Quick Reference: Conventional Commit Format

Concrete Examples

Example 1: Multi-Step Commit with Conventional Format

Example 2: Bug Fix with Related Test Update

Example 3: Refactoring with Multiple Files

Validation Checklist

Related Skills

prulloac/vscode-extension-builder

prulloac/system-prompt-validator

prulloac/skill-validator

prulloac/skill-creator