- Each commit should be a single logical change. Don't make several logical changes in one commit. For example, if a patch fixes a bug and optimizes the performance of a feature, split it into two separate commits.
- Don't split a single logical change into several commits. For example, the implementation of a feature and the corresponding tests should be in the same commit.
- Commit early and often. Small, self-contained commits are easier to understand and revert when something goes wrong.
- Commits should be ordered logically. For example, if commit B depends on changes done in commit A, then commit A should come before commit B.
- Test before you push. Do not push work that is half-complete.
- Limit the subject line to 50 characters.
- Capitalize the subject line.
- Separate the subject name from commit description (if any).
- Do not end the subject line with a period.
- Use the imperative mode in the subject line. In other words, name it as if giving a command or instruction. A few other examples: "Clean your room", "Close the door".
- When committing to fix an issue brought up in a PR, refer to the PR # like so:
[PR139]Fix typo in introduction to user guide
Tip: If you’re having a hard time summarizing, you might be committing too many changes at once. Strive for atomic commits.
To remove any confusion, here’s a simple rule to get it right every time. A properly formed Git commit subject line should always be able to complete the following sentence:
If applied, this commit will [your subject line here]
- If applied, this commit will refactor subsystem X for readability
- If applied, this commit will update getting started documentation
- If applied, this commit will remove deprecated methods
- If applied, this commit will release version 1.0.0
- If applied, this commit will merge pull request #123 from user/branch
Notice how this doesn’t work for the other non-imperative forms:
- If applied, this commit will fixed bug with Y
- If applied, this commit will changing behavior of X
- If applied, this commit will more fixes for broken stuff
- If applied, this commit will sweet new API methods
The body should be used to explain what and why vs. how. Just focus on making clear the reasons:
- why you made the change in the first place (the way things worked before the change and what was wrong with that.)
- the way they work now
- why you decided to solve it the way you did
- what side effects it might have