The concept of good messages to go along with your commits to source control seems to be one of those things that people either completely follow o...
For further actions, you may consider blocking this person and/or reporting abuse
One thing the consider is what the benefit of the commit message will be long-term. In the future, when the context is no longer fresh in your team's mind, you might be debugging an issue or building code based on the code in the initial commit. For me, I'm much more often asking "why is this here"/"why is this like this" than "what does this do" (because I have the context of "what does this do" from reading the code itself).
I often find myself pleasantly surprised when I'm debugging an issue with some code, say to myself "what was I thinking", hit
git blame
/git show
and immediately know the context.I think the card number is definitely great, but I don't think a distilled explanation in a commit message is a a waste of time either. Another small nuance is that the commit message is written in your own voice with your own understanding of the problem, at the point in time that you've just written the code, so you're in a much better place to write a technical description of what you've just done (in my experience, finished code often deviates from the plan).
It does take longer to write the commit message, and I agree that it takes a lot to move a team to this practice, but I can personally vouch for the benefits!
I stumbled on this not long ago and I'll share here as I learned from it. Based on Angular's convention for commit messages. Here's the link
Basically like this:
I've taken that knowledge and adapted it into what I do. The
<type>
part I am flexible with.I've seen similar. I've used the karma git template which is this. This link has more detail though while I'll use to train with in the future. Thanks!
Be sure to check out the angular documentation which is a few clicks and a google doc away...
here
Sounds like a good convention! I'll look into the link later today, thanks!
I'd like to offer a deeper tip here. It is good practice to keep commits to functional units of work. A story might, and should, contain multiple commits.
Then your final commit of the story can contain a git message footer that links back to the story number.
Then you can also separate units of functional code apart from refractors and doc chores.
This will make code review and reviewing the git history a lot cleaner!
Great post! Commit messages are important on large projects with multiple team members.
First, thanks for sharing @rachelsoderberg ;)
Just came down here to write the same, I consider commits as the good old video game checkpoints.
Every time you hit a "safe place" where you would like to go back in case of something goes wrong, add a commit with a very descriptive message.
Your "future myself" (and code reviewers) will thank you a lot.
Further reading: pauline-vos.nl/atomic-commits/
Love the analogy, I think of it the same way š
Thank you! And that is a great point - a lot of times I commit every time I have finished a solid (hopefully working) portion of the card. Basically if I'm going to step away for a break and would regret losing what I built, I commit. If what I commit isn't working, I make sure to specify what doesn't work and why.
I would urge against commiting incomplete code. It really is a matter of opinion and process but for my team of 12 working on a large project keeping our git history clean is really helpful.
Some more tips to consider:
If you need to port code to another machine to continue working you can create a patch file:
git diff > patchfile
git apply patchfile
Or, if you do commit a temporary commit you could also squash the commits together using interactive rebase
git rebase -i HEAD~2
Great post, and one that more people need to read (and I need to adhere to more often). It's so easy to get lazy. Also, I think what I've noticed with myself and others is sometimes a commit message or commit includes far more than what's in the actual changes which can be problematic.
Thanks for triggering a discussion on a topic that deserves it and is very important.
I find that this article would gain from being refactored from a "this is what good commit is" to "this is how I commit".
Many of the things it recommends are far from consensual or standard, as pointed out by several comments. Similarly, the examples lack several features which are often considered as required for good commit messages.
As a consequence I think it would be more helpful for young programmers and for the community if it took a less normative approach, and rather a more descriptive one.
You make a good point, I am one of those young developers and probably made the article name a little too "absolute" as in everyone does them this way, rather than implying that it's my understanding of them.
I'm curious too - if you don't mind, what features did I miss that would be considered required for good commit messages?
Thanks for the comment, I always appreciate constructive criticism & feedback!
I am glad that you are receiving my comment positively!
It would probably take a whole blog post to answer your question, but I guess what comes closest to my opinion is this: chris.beams.io/posts/git-commit/
Best of luck for the start of your career!
Thanks - and thank you for the link! That will be good reading, I appreciate it.
Prepend commits with the file or component which it is affecting.
Readme: add install instructions
In git, there are commands to see what files a commit changed - to me, prepending files names seems unnecessary
I agree with the component / subsystem - the file is just a special case of that (of a very small component).
We did this at my last job as well. Either the filename or if it's multiple the source of the changes. It makes for a much easier to read git history / merge request.
Visual Stuido Team Explorer shows them as well, but this makes sense for ones that dont!
Here are the rules that I did save from one of the sources some time ago.
You also only want to change what you say is changing. I've pushed for using gitmoji in every commit. The goal is to help review what the changes are supposed to do and make it fun to try and craft a commit to use a specific emoji.
Some of them should never make it to mainline though.
This is great! Commit messages are one of those weird parts of the development cycle that feel like they're just some boring, but necessary admin task. Having some guidelines (and enforced templates) help, but your article does a grand job of showing what bad and good messages look like and why the latter is important.
I also agree with Kyle's comment about context, but then you can also add a little more detail in the commit body for that where it's needed.
I'd recommend against writing the card/issue number in the first line. It's the summary line and IMO it takes away precious space I'd rather use for a good summary. I put the issue number in the last line of the message. We are using gitlab and I can easily search for it in the GUI if that is necessary.
Have you looked at Commitizen? I find it useful for prompting me to write better commit messages.
I havent, but I'll certainly check it out later today! Thanks for the tip
Great post! It pretty much explains the way my company does commits, though I think we all need to work on committing more frequent, smaller bits that can easily be explained by a simple message.
When writing commit subjects I found a good tip saying to start a sentence with "If you applied this commit then it would..." then use the rest of the sentence as the subject line.
That is a brilliant tip! I might just have to steal that and add it to how I currently do them. Thanks for sharing!