Multi-Commit Workflow (Conventional)

Overview

Break a mixed-delta branch into focused conventional commits by planning the sequence, staging deliberate hunks, and reviewing each set before committing.

When to Use

• The working tree touches multiple features, refactors, or fixes that should not be lumped together.

• Preparing a pull request that must demonstrate ordered, reviewable steps.

• Sharing code where readable history matters for reviewers or downstream owners.

When NOT to Use

• Single-feature changes that are already isolated.

• Quick typo or documentation fixes that can be handled as one commit.

Quick Procedure

Quick Procedure

• Inventory: git status -sb → note files; skim git diff --stat for clusters.

• Plan: Draft a commit table (order = dependency then narrative): type(scope?): summary . Keep commits orthogonal and testable.

• Stage per commit

• Path-based: git add path/to/file .

• Hunk-based: git add -p path (use s split; e edit).

• Unstage if needed: git restore --staged <path> .

• Review staged: git diff --cached (ensure only intended hunks). Add brief inline comments in PR later, not here.

• Commit: git commit -m "<type>(<scope>): <summary>" with guidelines below.

• Repeat for remaining commits. End with git status (should be clean or only intentional leftovers).

• Validate history: git log --oneline -5 to check ordering and messages.

• Push: git push -u origin <branch> (or git push if upstream set).

Conventional Commit Cheatsheet

• types: feat, fix, chore, docs, style, refactor, perf, test, build, ci, revert.

• scope: optional; use folder, package, or short noun (e.g., api , ui , infra ). No spaces.

• summary: max ~72 chars, imperative mood. Avoid trailing period.

• breaking: add ! after type or scope; include BREAKING CHANGE: ... in body if needed.

Examples:

• feat(api): add pagination to reports list

• fix(auth): handle expired refresh tokens

• chore: update README install steps

Planning Tips

• Group by user-facing behavior or deployable unit; avoid mixing refactors with functional changes in one commit.

• Order commits so tests/builds pass at each step; fixes before refactors only when dependency exists.

• If a file belongs in multiple commits, use git add -p to separate hunks.

Safety Nets

• Inspect unstaged leftovers before final push: git diff .

• Amend only the most recent commit when it doesn’t affect reviewed history: git commit --amend (avoid after sharing).

• To reorder without losing safety, use git rebase -i HEAD~N (only if branch is unpublished); otherwise create follow-up fix commits.

Minimal Body Template (when needed)

<type>(<scope>): <summary>

Context: <why this change> Testing: <commands run or N/A>

Publishing Checklist

• All commits pass tests they touch (run focused commands per commit if feasible).

• git status clean; remote set.

• Push and optionally draft PR with concise summary of commit plan.