When it comes to version control, I advocate for making many small, focused commits rather than large ones.
And while I'm alive, I'll make tiny changes to earth.
— Frightened Rabbit
Best Practices: Tiny Changes Add Up
The goal isn't just to make commits small, but to make them focused and purposeful. Each commit should represent one logical change to the codebase.
At the end of the day, we may arrive at the same changes, but small commits help us manage our time and ensure our tasks are completed correctly, while leaving useful information for the future.
Break large projects into smaller tasks. This is a traditional project management skill that is a critical part of making good use of your time and producing successful outcomes. Parkinson's Law suggests that tasks expand to fill the time allotted them, so being able to identify more, smaller tasks helps limit the time creep.
Think about how a task translates into a descriptive commit message. If the tasks or messages overlap or are similar, can you merge those tasks? If not, identify the key differences to distinguish them. Pro Tip: If the word "and" appears in your commit message or it takes multiple sentences to explain, your commit should be split up.
Make sure your commit leaves the project in a working state. While not always possible, this guideline really helps when multiple developers are working on a single repo. When we leave the project functioning we can create and merge branches more often and limit conflict. And, should you need to roll back changes, you are more likely to leave the application functional.
Review your own changes before committing to ensure focus. Sometimes we find opportunistic changes or lose sight of the primary task. While we don't want to lose those insights and updates, there are a number of ways to isolate changes in version control tools and IDEs to keep commits distinct.
Consistency
As the number of commits increases, it can be hard to keep your commits meaningful. Consider adopting a style like Conventional Commits for clarity and consistency.
Benefits
The benefits of small commits become apparent in several key areas:
Easier Code Review
Small, focused commits are easier to understand and validate. Reviewers can look at different commits in isolation and focus on the relevant details for each smaller unit of work.
Smaller commits create less risk of reviewer fatigue and produce higher overall quality.
Ask a programmer to review 10 lines of code, he'll find 10 issues. Ask him to do 500 lines and he'll say it looks good.
– Giray Özil
Better Debugging
Small commits make it easier to identify where issues were introduced. With granular commits, you can more effectively use tools like git bisect to pinpoint problems. Once a defect is identified, small commits help us limit the risk and testing scope of changing existing code.
Cleaner History
Each commit should tell a story about a single change. When commits are small, that story becomes clearer and more meaningful to future developers, including yourself.
As project ages increase, the commit history can tell us about paths taken and abandoned, about errors resolved and risks to be aware of. The better the and more specific the commit messages, the easier it is to understand the project history.
Safer Merges
When commits are small, not only does the risk of merge conflicts from overlapping changes drop, but it is also easier to resolve conflicts with smaller changes.
Safer Rollbacks
As mentioned before, if something goes wrong, rolling back small commits is less risky than trying to undo large chunks of interconnected changes.
Lower Risk
Uncommitted code is like having an unsaved document. The more time that passes between a line of code being modified and being checked in, the more opportunity there is to lose that change. Accidental deletion; overwriting; failing to stash a change before switching branches; resetting a branch instead of a file...there are many ways we can lose work.
Im modern version control like Git, branching is practically free. While git stash can be useful in a pinch, it requires almost the same effort to create a temporary branch which can be merged into a feature or maintenance branch should it end up being valuable.
Committed changes can be pushed to a branch or fork of a repo on a server, allowing others to view and work on them collaboratively and ensure your locale system isn't a single point of failure which can cost you that work.
Should You Squash?
When creating many small commits in a feature branch, it may be desirable to squash these into a single commit at the end, ideally using the pull request so you don't lose the discrete history that is so helpful during code review.
I prefer to keep the history, but it also depends on the scope and frequency of these merges.
Themes, not Things
We often don't need every small change to be represented in the end, but if the commits don't share a leitmotif – a single, overarching theme – then they likely shouldn't be squashed together.
This ties into the Cleaner History benefit. While the work is happening, these separate messages may make it easier to spot mistakes or inconsistencies in the code review:
refactor: JIRA-12345 - Replace guards with optional chaining
refactor: JIRA-12354 - Replace logical OR with nullish coalescing
Once the work is validated and ready to merge, a single squashed commit can represent them:
refactor: JIRA-12345 - ES2020 update
Squash Early, Squash Often
If your branch includes a number of refactoring commits, consider merging and squashing those before you do additional work on your project. That allows the refactoring to be represented as a single commit in the broader history while remaining separate from the project work.
This further isolates the risks of different tasks into separate history entries and encourages shorter branch lifespans, keeping the risk of conflicts low.
Conclusion
It can take getting used to if you aren't accustomed to the style, but small commits can help improve your code quality and development process.
Practice creating smaller commits. Like almost all of version control, the payoff for your work today comes in benefits for yourself and others down the line, but that day can come sooner than you expect.
Top comments (0)