refactor: Code Refactoring
Learn how to use the refactor commit type for code restructuring that doesn't change external behavior. Understand the difference between refactor, fix, and feat.
Detailed Explanation
The refactor Commit Type
The refactor type indicates a code change that neither fixes a bug nor adds a feature. It restructures existing code to improve readability, maintainability, or performance characteristics without altering the external behavior. Under Semantic Versioning, refactor commits do not trigger any version bump.
Example Messages
refactor: extract validation logic into separate module
refactor(auth): replace callback-based flow with async/await
When to Use refactor
Use refactor when your commit:
- Renames variables, functions, or files for clarity
- Extracts code into reusable functions or modules
- Simplifies complex conditional logic
- Reorganizes file or directory structure
- Replaces one implementation pattern with another (e.g., callbacks to promises)
- Removes dead code or unused dependencies
The Key Rule: Behavior Must Not Change
The critical distinction is that a refactor must not change any observable behavior. If your restructuring:
- Fixes a bug → use
fix - Adds new capabilities → use
feat - Improves measurable performance → use
perf
Good Refactoring Descriptions
| Bad | Better |
|---|---|
refactor: refactor code |
refactor: extract email validation into util |
refactor: clean up |
refactor: simplify nested conditionals in parser |
refactor: misc changes |
refactor: replace class component with hook |
With Body for Context
refactor: extract validation logic into separate module
Move email, phone, and address validation functions from
UserController into a dedicated ValidationService. This
reduces the controller's responsibility and makes the
validators reusable across other controllers.
No behavioral changes - all existing tests pass.
Use Case
You have spent time simplifying a complex function by extracting several nested conditionals into well-named helper functions. All tests pass and the output is identical, but the code is now much easier to read and maintain. You need a commit message that explains the restructuring without implying any functional change.