Horizons of Git Commit
FleetingWhen writing code, there are several milestones you generally reach.
When teaching git to colleagues, I realized I always told the same story, so I decided to write it down once and for all.
I hope it gives some general guidelines of what to commit, push and tag and what to write in the commit messages.
I firmly believe that people that write 100K lines commit with the message “fix test” don’t have bad intention. Also, I think that this kind of commit is problematic.
I hope that getting the feeling of how (I think) you should publish your work, you will eventually have the habit of doing somehow correct (at least for me) commits.
An intended pun
Naming those “horizons of git commit” is a pun with the horizons of commitment from the gtd. But after smiling a bit, I realize those are quite related. In both cases it is a way to describe how you feel with relativity to your work and it gives guidelines to your future work. Also, even if I describe them in a bottom up order, sometimes you have to consider them in a top down fashion, like when the tag is the objective that drives the rest.
Here are the horizons I can think of so far.
Horizon 1: Ctrl-C: the word/sentence commitment
You generally don’t press CTRL-C at any random time during code writing. You generally press it after finishing a word, a sentence or a paragraph.
This is your way of saying: “I ended something that makes sense. If my program crashes, I want to go back from here.”
Horizon 2: git commit: the elementary intention commitment
When you have edited and saved a file, another file and yet another file, you reach a program state that make sense as a whole. Something that builds, that you can explain.
In that case, it is time to create a git commit. As a message, you explain what this group of changes brought to the program. You generally explain the intention here, like “Add the support for feature X”.
The intention generally does not reflect exactly what you did to the files, so please here avoid syntactic description of the message like “Added a comment”, “removed a line”, “added a parameter” but tell semantically what you wanted to do, like “explained the algorithm”, “make code clearer by removing unused line” or “exposed the feature X”.
Also, don’t be to vague on the intention. Don’t write “fixed tests” but instead tell why the tests failed in the first place and what you did to fix them. Again, don’t tell syntactically your actions, like “added the character ’s’”, but describe it semantically, like “make the message coherent”.
Also, if you feel like describing your intention involves the term “AND”, that probably means that your commit is no elementary. You definitely want to split it in two commits.
For instance, “Added the function X and used it to implement Y” should become one commit “Added function X” and another “Used function X to implement Y”. If you feel like both are intrinsically connected and should be committed together, most likely this summary is a detail and you should think about the bigger picture intention, like “Implementing feature Y” and then, as message body, you can tell that this implied “Implementing function X”. Yet in that particular generic example, I still believe two commits are better than one commit.
Horizon 3: git push: the story commitment
At some point in time, you find out that the succession of commits you did made a coherent whole. For instance, you implemented a feature, tested it and made use of it in some other part of the program.
At that point, you should have the feeling that someone getting the code in its current state could play with it without getting the feeling that some work was in progress.
This is in general the good time to push your work, so that others can pull it and use it.
You generally want to take a look at the commits to rework them before hand, yet in collaborative work, I understand it is not easy.
There are two common behavior I don’t encourage:
- One is to push after each commit (svn style). This makes the remote branch show your work in progress instead of something publishable;
- The other is to never push, because you always feel like you are in work in progress. I feel like you have to give yourself small iterative objectives and each push should be the reflect of such step.
Horizon 4: git tag: the publishing commitment
At a final point, you realize that you have reached a milestone. The successive stories you wrote tell a bigger story that you want to tell the world.
Also, you know that in the future, if at some point, you’ll want to advice someone to use your product, you can advice this version.
Also, if at any point in time you need to take a step back because you don’t like your work, you will always able to rely on this version to start again.
In general, this is the good time to create a tag.