Comprehensive Commit Module

A comprehensive skill for managing git commits — covering commit message conventions, interactive staging, atomic commits, commit history management, fixup and squash workflows, and team commit policies for clean, navigable repository histories.

When to Use This Skill

Choose Comprehensive Commit Module when you need to:

• Create well-structured, atomic git commits
• Stage changes selectively for granular commits
• Squash, fixup, or reorder commits before merging
• Set up team commit message conventions and enforcement
• Clean up commit history before submitting a pull request

Consider alternatives when:

• You need PR workflow guidance (use a PR management skill)
• You need git branching strategies (use a git workflow skill)
• You need commit message format only (use a commit message skill)

Quick Start

Copy
# Stage specific files (not everything)
git add src/auth/login.ts src/auth/session.ts

# Commit with conventional format
git commit -m "feat(auth): add session-based login flow

Replace JWT token auth with server-side sessions.
Sessions stored in Redis with 24-hour TTL.

Closes #142"

# Stage and commit interactively by hunks
git add -p  # Review each change individually

# Amend the last commit (before pushing)
git commit --amend -m "feat(auth): add session-based login flow"

# Create a fixup commit for an earlier commit
git commit --fixup=abc1234
git rebase -i --autosquash main

Core Concepts

Atomic Commit Principles

Principle	Description	Example
Single purpose	One logical change per commit	"Add login form" not "Add login + fix header"
Self-contained	Commit works on its own (tests pass)	Never commit broken code
Reviewable	A person can understand the change	Keep diffs under 400 lines
Revertable	Can be reverted without side effects	No unrelated changes mixed in
Bisectable	git bisect can find bugs	Every commit compiles/runs

Selective Staging Workflow

Copy
# Stage specific hunks within a file
git add -p src/auth.ts
# y = stage this hunk
# n = skip this hunk
# s = split into smaller hunks
# e = edit the hunk manually

# Stage specific lines (more granular)
git add -e src/auth.ts
# Opens editor showing the diff
# Remove lines you don't want to stage

# Verify what's staged vs. unstaged
git diff --cached    # Shows staged changes
git diff             # Shows unstaged changes

# Commit only staged changes
git commit -m "fix(auth): handle null session token"
# Remaining changes stay in working directory

Commit History Cleanup

Copy
# Interactive rebase to clean history
git rebase -i main

# In the editor:
# pick abc1234 feat: add login form
# squash def5678 fix typo in login form
# pick ghi9012 feat: add session management
# reword jkl3456 wip: dashboard → feat: add dashboard layout

# Fixup workflow (auto-squash into target commit)
# 1. Make a fix for an earlier commit
git commit --fixup=abc1234
# 2. Auto-squash during rebase
git rebase -i --autosquash main

# Split a large commit into smaller ones
git rebase -i HEAD~3
# Change 'pick' to 'edit' for the commit to split
# git reset HEAD~1  (undo the commit, keep changes)
# git add file1.ts && git commit -m "feat: add component"
# git add file2.ts && git commit -m "test: add component tests"
# git rebase --continue

Pre-Commit Hooks

Copy
# .husky/commit-msg (using Husky)
#!/bin/sh
npx --no-install commitlint --edit "$1"

# commitlint.config.js
module.exports = {
    extends: ['@commitlint/config-conventional'],
    rules: {
        'type-enum': [2, 'always', [
            'feat', 'fix', 'docs', 'style', 'refactor',
            'perf', 'test', 'chore', 'ci', 'revert',
        ]],
        'subject-max-length': [2, 'always', 72],
        'body-max-line-length': [2, 'always', 100],
    },
};

Configuration

Parameter	Description	Example
convention	Commit message format	"conventional"
max_subject	Maximum subject line characters	72
require_body	Require commit body for non-trivial	true
enforce_hooks	Use pre-commit hooks for validation	true
auto_stage	Auto-stage tracked files	false (prefer explicit)
sign_commits	GPG-sign commits	true

Best Practices

1. Never commit with git add . or git add -A — Adding everything stages unrelated changes, debug files, and accidental modifications. Always stage specific files or use git add -p to review each change. Selective staging is the foundation of atomic commits.

2. Ensure every commit passes tests independently — If someone checks out any commit in your history, the code should compile and tests should pass. Commits that break the build make git bisect useless and create landmines for anyone who needs to revert.

3. Clean up history before merging, not after — Use interactive rebase to squash WIP commits, fix typos, and reorder changes before creating a PR. After merging to main, rewriting history requires force-pushing, which affects the entire team.

4. Use fixup commits instead of amending pushed commits — If you need to fix something in a commit that's already pushed, create a --fixup commit and squash it during rebase. Amending pushed commits requires force-pushing, which disrupts collaborators who've already pulled.

5. Write commit messages for the person debugging at 2am — Your future self or a colleague will read this commit message while hunting a bug. "Update stuff" is useless at 2am. "Fix race condition in session refresh that caused duplicate cookies" tells them exactly what changed and why.

Common Issues

Interactive rebase produces merge conflicts — When reordering or squashing commits that touch the same files, conflicts are expected. Resolve them at each step of the rebase: fix the conflict, git add, then git rebase --continue. If it gets too messy, git rebase --abort and try a simpler rebase strategy.

Pre-commit hooks slow down development — Complex linting and testing in pre-commit hooks frustrate developers. Keep pre-commit hooks fast (under 5 seconds): run only commit message validation and fast linters. Move full test suites to CI instead of pre-commit.

Team members bypass commit conventions — Some developers use --no-verify to skip hooks. Address this by running commitlint in CI as well — reject PRs with non-conforming commit messages. Convention enforcement must happen at the PR level, not just locally.