I don't know if this is common or not, but I have a really hard time remembering to commit my code. I know commits are supposed to be meaningful and logical chunks of work that tell a story when viewed in aggregate. And yet... I still find myself chugging along until I get ready to get up from coding without having committed anything! My commit is a giant blob with a message like "finished most of the features." Hopefully there is someone out there who is like me. Hopefully this post speaks to that one person who hyperfocuses on a problem and forgets to commit (or move, or eat, or go outside, or speak to other human persons). Because I discovered a solution.
Plan. Your. Commits.
That's it! Mind blown right? Who could have conceived of such genius?! Surely no one has considered envisioning what you are about to do before you do it before now! Shut up, it was a new idea to me. Here's my thought process:
A lot of the tutorials that I've gone through where Git has been included seem to assume you are a pro committer already. They say things like, "There we go, that seems like a good spot for a commit," or "You'll want to commit your work now." This led me to believe that I could just code along and it would be abundantly obvious to me when I should be committing.
However, I have found that if I preselect my checkpoint, I forget less. Saying things like, "I'll commit again after I've finished this function," or "after I get the url routing hooked up" works a lot better. Mostly. The idea is that once I get there, I can commit, come up for air, see where I'm at, and see where I need to go. It also helps me not need to hold everything in my head and helps (some) for if I leave the project alone for a few days and want to come back. More stuff is written down and less is bouncing around in my head.
So, if your commits look like a pile of [rhymes with commit 💩], try writing your commit message (in your head) before you write the code. If you have a better way, OR, if you have other tricks that would help me keep my head on straight in the long run, please share them! I'd love to hear them.
Oldest comments (40)
If you break up your work into discrete tasks (or user stories) it makes committing code a much more logical procedure. Plan a task, create a new branch for the task, commit logical chunks (or your own choosing) until the task is complete and then create a PR to be reviewed a before merging branch into master or if not on a team just merge yourself.
If you are new to planning your own work, using something like Trello will help you to break up your work. The smaller the chunk of functionality the better from my experience because it keeps you focussed on documenting your commits and gives you a continuous sense of achievement.
When you do Test Driven Development, a completed test is a very logical point in time to do a commit. Also, it's kind of a breaking point because you will then step to another piece.
With this approach, you get very granular commits (which I personally love)
Absolutely. After I read the article, seeing that the author had trouble in the past finding a good point to commit, I searched for "test driven" just to see if anyone else had the same intuition.
The hard part about using TDD to drive commits is that writing good tests is a very different skill from writing good code, and that you'll (initially) sink a lot of time into writing, maintaining and debugging tests instead of staying in the flow and just writing a test, see it fail, write some code, until you find that the tests you have are sufficient. I think I had to do TDD every day for almost a year before I was able to find good commit points while writing tests.
Great post. I, too, have found myself in this position. I think what @jonbloomer and @johannesEbner commented are also very helpful. I think the most important point is, you must plan. It doesn't mean the plan can't change--but you must have a logical series of steps you want to take to accomplish anything useful. Once this plan is in place, committing becomes easy.
Thanks for sharing.
As an experienced engineer, I struggle with the commit cadence and find it is a personal development style - others might commit more or less frequently than I do.
As mentioned, break up your features or tasks into branches. Commit often on your local/remote branch at crucial save points or to mark work in progress with commit messages that at are short but to the point.
When you are ready for a pull request and to merge to master,
git rebaseis your friend. This command allows you to squash your mini commits into a one nicely worded and descriptive commit about the changes you have made.A fellow engineer at Spreedly has a great blog post on commit messages
So true! Sometimes it helps me to
git commit -m "wip"after every tiny change and thengit rebase -i [branch]once I'm done — this way you can undo every single change in case you fuck up somewhere along the way and after you're all done you can squash the witty wips into one coherent, well-explained message (and nobody will ever know that you broke everything three times in the process)Commits absolutely do NOT need to be some coherent chunks, they should be whatever state you feel you want to save. Work in feature branches, make as many or as few commits as you think is suitable, and then when merging use a good merge message describing the feature or changes.
Often if you name your branch
feature/new_loginand merge that, the common auto generated message that is something likeMerged feature/new_loginis descriptive enough.If your workplace has some strict policies about commits having to be coherent, or planned, you should complain or work somewhere else. The policies and tools should be made so your life becomes easier, not harder, and if you need to plan when you can commit you're making your life harder.
What you SHOULD strive to do is keeping your clone in a state that you can always push and pull, and you don't need to be afraid of breaking something, or something breaking on your end.
I often commit when I've done a significant amount of progress or when I finish the feature or bug fix, and when switching tasks, not much more often than that. When I realize I've got multiple unrelated changes I'll commit them separately. I'm not scared of committing something that's broken or not complete, as I never work on a branch that's supposed to immediately go live, or someone else depends on.
Instead of planning your commits, you SHOULD pay attention to what you commit though. Don't do blind commits of the
git add . && git commit -m "stuff"-style that way too many people do. Make sure you actually know what changes you are committing and that you didn't leave debug code or similar things around, unless you need it when you continue working.Use a GUI tool to diff the changes (your IDE should help here). Make sure you use a similar visual diff to re-check all your changes when merging your branch (or pull request). Beyond that there really isn't a need to "plan" things out.
There's more people in this world, and in your company, than you, dude. Just because you feel like it's too much of a burden to write a good commit message does not mean the tool is getting in your way. The entire point of git is to have a history, to be able to look at it, and revert certain parts of it. Step one of doing all of that is having a coherent history.
I've been programming using DVCS systems for a living and in teams for quite some time, and know exactly what level of effort you need to put into your DVCS usage to make it easy for other members of the team.
I didn't say your commit messages should be "a" or "stuff", but there is literally no need to be super careful with your single commits, as long as you work on feature branches.
If you're not using feature branches (you should) you must at the very least make a very good commit message, but really you should be using feature branches. When you create your feature branches the name should be clear enough that you don't need to read the commit messages to understand what it's about. Any additional information reviewers might need can be attached into the PR, and the task/issue related to the changes.
If you directly make a single commit to
masteror similar for your whole feature, you're doing it wrong.Some of what you say makes it sound like your workplace doesn't do code reviews. Reviewing changes submitted as incoherent batches of commits is a pain, to put it nicely. Especially if they're large commits. Especially if they're so incoherent that there are a bunch of changes mixed in that are completely unrelated to the change I'm reviewing.
No, code reviews are really simple. Do a PR on GitHub, or BitBucket, or whatever you use and you get a diff of ALL the changes in a branch. If you don't use those tools, you can always do a merge locally and view the full set of changes. I've been doing this for quite a few years and there is no problem in viewing all the changes in a feature branch.
Just learn to use the tools you have instead of making everyone spend extra effort.
The tools can't exclude a bunch of irrelevant changes if they're submitted with the code to be reviewed. Instead of the submitter doing a little extra work they're forcing the reviewer to.
The tools can't explain why changes were made when a bunch of commits have a single comment that doesn't explain anything, like "feature completed". Instead of the submitter doing a little extra work they're forcing the reviewer to.
If everyone learned to use the tools well there wouldn't be these problems, obviously, but it's clearly not as black and white as "Commits absolutely do NOT need to be some coherent chunks".
So don't commit irrelevant changes to your feature branch, this falls upon the "blind commits" -category of problem.
The best way to explain why certain changes were made is not in the commit messages as you should not review separate commits but the end result of the work in the feature branch.
What I do if some change is unclear is usually one of the following:
Oh and if you don't know which of the changes you made are relevant to your feature branch anymore you don't commit often enough.
I agree, and hopefully can add to this a bit:
If you're having problems with unrelated work sneaking into a branch, then you probably have one or more of the following issues:
Like @Duke here, my team does frequent PR reviews and frequent merging (and once we have our CD stuff fixed, we'll be releasing on merge) and we don't have a problem with commit messages as they're mostly a personal thing that doesn't survive the merge (due to squash merging).
Master is kept clean by just squash merging. Individual commits are for the individual(s) who is(are) driving the branch. Usually the branch scope is small enough that it only lives for 1-2 people for maybe a week or so. (Also, you're not allowed to merge your own PR.)
But most of the time, it's too much a hit to individual productivity to worry about mandating a certain commit cadence or making messages be meaningful beyond a few hours after merging.
Totally agree with having a plan of attack! With more complex changes, I do that as part of pre-writing as described here:
dev.to/jlhcoder/just-in-time-docum...
I was having this problem at work too, until I decided to add sub-tasks to my assigned tasks.
So for each sub-task that should be one step into solving the overall bug or implementing the feature, I create a commit.
For instance, If I have Task "x", I would divide it into Subtask 1, Subtask 2, and so on. And commit each working subtask. And when I'm done with the whole task I push the changes.
What I often find myself doing is making multiple logical changes at once and then interactively adding them to the commit with
git add -iin chunks to separate out what I've added. It's easier for me as I don't always have a clear vision in my head when I set out as to what will need to be changed exactly. But when I go through the chunks it helps me to visualize the edits I've made and to logically group them and see where I might have missed changing something and allows me to commit them also in an order that makes sense.I was able to improve this gut feeling about when to commit a lot. Basically I was forcing this technique on myself and, as many others already have stated, create a commit for each subtask (if the project was well managed and had tasks and subtasks, of course). Although all of this comes more naturally to me now, I still often end up mixing two or three commits, but I think saying "aw, crap" and throwing all the changes into one commit is the wrong way then. What I do instead is take the time, extract the single logical units from my pile of changes (if you have a git client that fits your way of working that should be doable - not naming any because taste is different) and commit them one by one. This can be tedious but enforces to remember to commit early next time - there are things you have to learn the hard way.
I've had the same struggles and tried the same solution. I even whipped up a Git extension to help the process: fractaledmind.com/projects/git-do/
It allows to actually write the commit message before you do the work, then just say when you've completed that work.