Commit messages guide
github.com
github.com
The same is generally true about rebasing etc.
Due to the high visibility of commit messages, a lot of details certainly look pretty bike shed-ish.
What can be important is simply a general concept of meaningful messages when they make sense. For example, bug fixes that may not be obvious by looking at the code, should probably have a reasonably detailed description of the bug. Commits implementing a brand new feature and involving a ton of changes, probably don't need a whole lot more than what the feature is and what is the expected behavior. Possibly some info about potential future bugs that could happen. When updating the readme, "Updating documentation" is just fine plenty of times.
Otherwise, probably just make sure you include some important keywords to make it easier for people to git-grep and I think most projects will be just fine.
There ar certain personality types that really enjoy organization and rules. And the feeling of security that comes from having a well defined set of procedures everyone must follow. It really isn't about making software more maintainable based on any existing research we have about how maintainable software is. But if it benefits some of my coworkers mental health by following those rules, it really doesn't take me any additional effort to follow those rules so I have no problem doing it.
A good git log prevents unnecessary headaches and saves a lot of time. Typical situation: you just found a couple of lines whose purpose is not completely obvious. If the author is still there, you both waste time discussing. If she/he left the company and you have to figure it out by yourself. Now imagine using git log to identify when these lines where introduced/changed and getting an explanation as to why.
So yeah, writing good commit messages can feel like a waste of time. Like writing good code can feel like a waste of time. You should not be doing it to please your colleague, but rather to contribute to a maintainable codebase. It’s worth the extra minutes here and there.
Bonus point: less documentation to write.
Note that commit messages don’t live with the code. If you find yourself writing why something should be in the new state, consider putting that “explain why” as a comment next to the code, so anyone’s text editor can read it.
Oh and while it doesn't "live" with the code, I can at least look up a line in question and see which commits have changed it, along with their commit messages.
The first job I had, I was working on software that had originally been developed by a software engineer but had then been passed to the stewardship of non-programmers.
Originally, it had been checked into CVS (yeah, it was that old), but the non-programmers didn't know what that was or how to use it, so when they started making experimental edits, they just copied the source folder to a new location and labelled it "NEW <project>". By the time I got involved there were over 200 of these folders on the network drive, it was unclear which one if any represented the head revision, and the machine with CVS on it had long ago been lost and existed only as a legend.
This wasn't insignificant software by the way. I don't feel like telling you exactly what it was, but it was an intense physics simulation and it has quietly impacted probably around a million lives over the last few decades.
The point is, don't assume your commit messages are as permanent as your code, they're not. Non-developers just barely grasp source code being important but they don't understand VCS history /at all/. Put important comments in your code.
Fortunately, DVCSs don't have that problem because the meta-information is stored in a folder within the source. So unless the non-developer deletes that folder in every single project, then the information won't be lost (but it wouldn't get updated either).
I can think of at least two ways off the top of my head to move the source from folder A to folder B while leaving hidden folders behind. They both assume you're using a graphical file explorer, like non-developers are likely to do.
The "explain why" that explains how the current code state works however should sit next to the current code.
> If you find yourself writing why something should be in the new state, consider putting that “explain why” as a comment next to the code, so anyone’s text editor can read it.
The problem here is that there's no guarantee that the comment gets updated when the code does. Whereas, a commit is always associated with the code at the time it was written. If the code is changed, then that old commit is no longer associated with it.
> if the code is changed, then that old commit is no longer associated with it
Right, this is my problem with putting “why” always only in the commit message: Sometimes the “why” is both durable and shouldn’t be buried by later commits. Suppose you refactor the code: you’ve put it in a new place or you add trailing commas or you replace positional args with keyword args. Now the most recent commit is the one that explains that transition. Code is a UI that a future engineer will use to understand the system. An important prose explanation is part of that UI and you might decide it should present itself as an affordance.
This is an exercise of technical-communication judgement: I’m proposing that you should ask, where the explanation should go. Should it be hidden for those looking through the history? Probably. Should it be clearly visible alongside the code? If it is important and durable.
Use commits for an audit trail of ticket numbers, urls, and playing the blame game.
Use comments for expressing the inferred. // That which is not explicitly stated.
> Increase left padding between textbox and layout frame
You would put that in your CSS file so anyone's text editor can read it?
Besides, what text editor doesn't support `git blame`?
I don’t think you’d add a comment like
/* 5px optimizes visual balance */
Either. Its just too small a detail that it isn’t worth directing your reader’s attention to that.
My proposal isn’t a rule, but rather a question to ask yourself and then to exercise your best technical-communication judgement about.
When I look at the repository I am happy if I can understand the messages at all. It's challenging to get people to group changes in a logical way so that the commit makes sense. I am not going to pick on somebody because he used wrong tense or did not capitalize first word of the message if the changes are grouped logically and the commit mentions the correct ticket and purpose of the commit.
Do you enforce consistent code formatting in your codebase (using CI, maybe)? If so, why wouldn’t you do that with commits?
At this point, the only reason why I like consistent code formatting rules is because they prevent bickering between people who have strong opinions on how things should be. When there's a rule, even if people don't like it, they abide by it. When there are no rules, everybody who thinks that there should be rules starts bikeshedding what they ought to be.
But as far as code quality goes, I don't think it matters much.
I'm pretty much just echoing what others have said, but when I look back at the things that have caused problems / mattered in a codebase, things like formatting are generally ranked an order of magnitude below everything else.
If people care, I'm happy to oblige, but it always seems like a missing the forest for the trees kind of thing.
How many code bases have you worked with that don't bother enforcing some type of standard with spacing/usage of tabs, indentation, variable names, method names, import order etc? People don't typically view those rules/conventions as nitpicky. Why should that change with commit messages?
A coment in code describes the state of the code as it is. A commit message describes a change in the code, a delta.
I would still argue that comments should explain why code has changed over time -- comments should provide context for someone editing the code, which can include descriptions of what the code used to do, why it has changed, why it hasn't changed (what was already tried and why it wasn't good enough), what else would be impacted by a change, and information about the quality of the code (is it a quick hack, or has it been optimized extensively?)
Naturally you don't need to supply all of this, and if the code is changing very frequently it might be easier to put that stuff in a commit message. (It also helps when you use small, pure functions, because they tend to not need much context to understand.)
They actually do stay with the code only as long as the code is present in the code base. The code can be updated independently of its associated comment, but the associated commit message will change.
This is probably unintentional - but i'm pretty sure this is a straw man - No one was implying not having commit message rules means project failure, but it might waste more time if they ever need to be reviewed by others or revisited in a git blame etc. Just like other project wide rules, it helps improve legibility and communication. However I find these rules to be few and general enough, well reasoned about to apply to any project.
I glanced at these years ago and just remembered them (50/72 + imperative mood, the remaining ones are just basic language stuff). I've never imposed them on anyone else but have recommended them, I mainly do it for myself (and I have benefited). The three I mention are the most important, the rest emerge from them (i.e imperative mood encourages you to talk about the effect, not just describe what the code already describes).
> There ar certain personality types that really enjoy organization and rules
I have similar disdain for excessive numbers of rules enforcement, but don't draw conclusions about how to utilise these. "rules" here, are just a way of formalising some principles that may help you write more useful and consumable commit messages - they do not have to be integrated into your org or project or whatever and enforced in order to be beneficial.
Well, I have seen failed projects where the complete lack of commit sanity wasn't the cause, but a very clear sign, of what was wrong. Perfect examples are commits labelled 'no changes' (the author's way of saying 'whitespace/formatting only changes', I think) but where addition of braces in languages sensitive to that actually caused behaviour changes. And more bugs on top of the existing trainwreck.
What can be important is simply a general concept of meaningful messages
This basically. All these commit message rules, whe applied, are just another way to force the comitter to reflect on what he/she is writing (both the message and the code), whether it makes sense, and so on. I've seen so many cases where someone had problems describing in simple terms what a commit was doing and why, just because the code was, well, a mess. Forcing the author to dissect both the commit messsage and code then usually makes it very clear how to improve both.
Clean commit messages fall into the same area as “good git hygiene” for me.
When I was consulting (mostly in the areas of DevOps and CI/CD), git hygiene was the very first thing of any new assignment I would take a close look at.
I joined a project that one of the main contributing factors in its failure was poor git hygiene. The real killer was a mess of branches that everyone had direct push access to. One of their repositories which contained cfengine infrastructure code was branched per environment. The configuration drift between the branches was so great that the dev team decided it was easier to throw away the entire codebase and rebuild production from scratch.
This is how I fell into training developers how to use git, because clean history is a very good indicator of the overall heath of the project.
One of the things I taught myself and then started teaching others is “always keep the head of you branch in a clean working state”. I recognized the common development commit pattern “do a thing” and then immediately afterwards “fix the thing I just did”.
Git never provided an easy way to squash/fixup those commits without popping up my editor, so I made my own little alias which others might also find useful: https://gist.github.com/philbert/c13ca7220951970225196cbce92...
git commit --amend --no-edit
I have recently joined to help failing internal project that had constant stream of production failures ranging from not being able to deploy new version to production for 6 consecutive deployment weekends to 10% of user interactions (like user submitting something to happen and this happening twice, or reporting success where nothing happen or just blew up in his face leaving him hanging).
It's been interesting to observe seemingly intelligent people avoiding really necessary tasks (setup oversight and monitoring, understand underlying problems and their impact, prioritize, fix). Instead, everybody spent their time attempting another Java upgrade (from 6 to 8), Spring upgrade, switch from Subversion to Git, from Maven to Gradle, setup automated code formatting rules or pick hard on others because they try to write simple code ("no, you can't check null with ==, that's what Optional is for...")
I understand some of that was trying to shift the blame but these guys didn't really have to shift blame for the application being in sorry state. Most of them joined recently and haven't been able to contribute anything substantial because of various rules that were designed to prevent anything substantial can get done.
I really liked literally 30s of silence after in a meeting with management and the team I asked if it is their conclusion that back in the days where Java 6 and Spring 2 were contemporary it was not possible to build reliable applications with them.
And "we have dependencies that have been EOLed and need to be upgraded" is easy to quantify and fix - whereas "The codebase is too large, complex and unfamiliar for us to recognise bugs in one another's contributions" is difficult to quantify and fix.
Necessary tasks are boring and it takes persistence to continously do what needs to be done. On the other hand checking various frameworks and endless rewriting may be considered fun by some. They're learning new things.
For the record I know how it feels as I've got a similar experience at work, people flock to new and shiny where old and tested works well and gets the job done.
Keep in mind that there are different degrees here. Commit messages should be informative, yes, but worrying about whether they start with a capital letter or are written in past or present tense is waste of energy.
I wouldn't be surprised if having to read several pieces of any kind of text, be it a commit message or code, which are not written in a consistent manner is more of a cognitive load than reading pieces which are. (And higher cognitive load probably leads to litereally more energy being used). So if those assumptions hold, and assuming you want tto waste the least amount of energy possible, the question becomes: what process costs more energy? Making sure the text is consistent and adhering to certain standards, or not doing that and waste more energy interpreting it and/or having to worry about that.
Good commit messages are super important in this case, of course, but the capitalization, verb tenses, and where line breaks occur have little to no real benefit, particularly if they're focused on over actually having a good commit message.
Also in my experience, passive-aggressive power trippers love anal retentive rules. Hence adding more than necessary carries a significant risk.
(This goes only for style guide violations, of course, not behavioral changes.)
Project failure is a pretty useless metric to go by; very few non-trivial/obvious reasons exist that would bring down an entire project on its own. And ofc, small things add up, larger than sum of their parts and all that.
But anyways, I agree this is a bit of a personality thing, but the most important aspect is that these kinds of issues fall into the bucket of “all options are fine, as long as only one is used”. That is, consistency is key; the flavor of it is minor. And thats trivially obvious in most situations; its much easier to read git logs if they all look/feel the same. It’s certainly more difficult otherwise. Not project-ending, but not nothing, and I’d argue its probably a enough more than nothing that its worth establishing a baseline.
Coding conventions reduce the cognitive load of developers by having a uniform look in the codebase.
Same for commit messages.
Then of course one can argue if a specific set of conventions is reasonable or not.
That could be said about a lot of things. I have not seen a project fail because they didn't use tests, so you shouldn't bother to write any?
To use a close analogy, surprisingly many professional developers need to be reminded about the proper use of indentation and comments. Not because the project doesn't build otherwise but because code generally needs to be read much more than it is written. The only code that is never read again is failed code.
The same is true of version control. A couple of years ago it was very popular to think in terms of storytelling. Your version control system is the story about why your software ended up the way it did. It's a story that every new developer will need to read, partially. Even if you are the masterful engineer that instinctively knows why "made bugfix" was written that way and not another, at least put in the effort for those of us who aren't.
This is a false equivalency. Commit messages do not validate that the program functions. I can just throw random garbage into the commit messages and the program with tests will still function.
I know what you are trying to convey, I just think it's a bad comparison.
I played around with several different tenses and styles for awhile and eventually came to nearly the same conclusions as the OP. If another style has genuine merit, then by all means, do what feels right. But if you've never given it a thought, just do these basic things. Use `git add -p` (to make atomic commits) and spend a few seconds crafting each your commit messages to conform to this standard style. In the long run having a standard style guide actually makes things easier for you as a committer.
Also the capitalising your sentence isn't a stupid nitpick. Broken window theory is real and if you're too lazy to capitalise your sentences in published work I'd hate to read your emails.
I think this is the same thing as using a linter and code formatter to enforce a certain coding convention for a given code base. I personally find projects that are written in inconsistent ways harder to reason about and harder to maintain because you have to keep track of multiple ways of doing various things rather than using a standard way of doing those same things.
With commit messages, having a consistent style makes them faster to read and easier to parse (whether manually or through tooling).
> Commits implementing a brand new feature and involving a ton of changes, probably don't need a whole lot more than what the feature is and what is the expected behavior
Describing the motivation behind adding a particular feature and it's possible advantages and disadvantages could be useful. It takes a lot less time to type that up than to figure it out by asking a bunch of other people or reading through disparate sources of incomplete documentation.
Also, there's a lot of unnecessary stuff in there. Capitalization and imperative? Not at the top of my list.
The relevant points are nicely summarized by Linus Torvalds: https://github.com/torvalds/subsurface-for-dirk/blob/a48494d...
> Git is strongly opinionated that the author is responsible for line breaks; if you omit them, command line tooling will show it as one extremely long unwrapped line.
In general, this approach is broken by design, because the author cannot know where the commit message is going to be displayed. It might actually be in the context where wrapping at 80 or even at 72 is still not long enough (a tooltip in an IDE, say). Or it might be one where it results in a lot of wasted whitespace. It's much better to fix anything that does not handle wrapping properly to do so, than to impose an arbitrary limit that only really works for one environment.
Or simply using a terminal with multiple windows open. I hard wrap at 50 chars and I haven't died from exertion yet.
Because there are some thing that shouldn't be soft-wrapped. Like code snippets, diffs, formatted output, etc. It's far easier to let the person who write the commit message to decide where to wrap it rather than relying on the recipient's display to do it for them. Linus Torvalds describes the same issue here [1].
[1] https://github.com/torvalds/linux/pull/17#issuecomment-56606....
Use the same spelling conventions as the auto-generated messages seems a reasonable request.
But it does seem like Linux is inconsistent about capitalization. https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/lin...
So it does. How are people managing to independently get this so wrong? The form used in a commit message isn't an imperative. It's an infinitive. No commands are being issued. This is like a purported grammar book telling you that third-person singular subjects use plural verb forms when the verb is in the past tense. The form is identical (except, in the example, for was), but the statement is obviously incorrect.
In the well-formed sentence
For cyanide to kill you, you need to be exposed to a lethal dose all at once.
Furthermore, idiomatic commit messages are pretty clearly not sentences, so I don't see why you think sentence structure should determine what they contain. And even on your own analysis of how the messages are interpreted (which I agree with), those verbs are infinitive, just as "fix" is infinitive in this dialog:
Q: What is this patch supposed to do?
A: Fix issue #351916.Infinitive. The predicate is "need" in this case. Swapping the order might make it clearer:
You need to be exposed to a lethal dose all at once for cyanide to kill you.And in the commit message "Add feature X", "add" is likewise an infinitive.
This directly conflicts with your earlier statement that
> The infinitive form of verbs in English always starts with "to", as in "to add", "to fix" etc.
That earlier statement is wrong, so contradicting it doesn't really present a problem, but you've left me pretty confused as to what you think you're saying.
Whether "be" is the "main verb" in that sentence is a more interesting question. There's a decent argument that it is, in that "this can be a hassle" is easily viewed as a modified form of the sentence "this is a hassle", but not as a modified form of the defective sentence "this can". But you're correct that the standard analysis just says that "this can be a hassle" is sentence where the subject is "this", the verb is "can", and the object is an infinitive clause.
At this point, he has been being investigated for six months.
Are all four of them "main verbs"?
Yes, short, clear commit messages are good. I'm not saying "write a paragraph"; I'm not even saying that it's bad to have an arbitrary maximum length beyond which a commit message can be considered poor form. It's just that 50 is a weirdly arbitrary choice.
I have a similar policy about line-lengths in code files. Sure, lines can be too long, but I find that codebases with strict line-length policies tend to have the opposite problem: too much vertical drift which makes it hard to see the big-picture of what is going on in the file.
* Link to issue in tracker (Projects can liver longer than the use of a single tracking software or use multiple in parallel - e.g.: public and private ones).
* Important changes in behaviour might warrant a deep link into the relevant docs, even though they are part of the commit.
* Justification why something was changed can be lengthy, especially in a loaded environment (crunch time, intra- or inter-team politics).
I am aware that various workflows exist, supported by various tools, that at least partially solve the problems I mentioned. But the larger the number of people involved or the longer the history of a project, the harder it tends to be to agree on a complete chain of tools just for the sake of keeping commit messages short.
I'm sure I've broken this rule many times, and I'm not aware that it's ever caused a problem.
I think it's worth noting that the actual text in a commit message stays with the repository. The contents of an issue referenced by the id does not. This is something to be considered especially if this is for an open source project or otherwise somewhere where the git repository itself is more important/central than the issue tracker platform.
I've worked with people who were adamant white space and formatting changes should always be in their own commit. But in my experience, it's never been a problem.
It's a pain in the ass. At least if the whitespace / formatting changes are in their own commit, then you can just merge that one first and continue on with your day, rather than having to manually resolve the merge problem potentially leading to more merging problems down the road.
Add different ways to format code in, say, C, C++, Java, and so on, and you'd add a whole lot of unnecessary complexity into a version control software...
Yes, being content aware is the key. No question, it isn't easy. I'm not sure it's possible, but one could imagine that another tool wraps itself around git, and has a better understanding of the full the underlying project, the languages used, and their dependencies.
Git can still be used for the lower level commits, but the higher level wrapper could do much more.
With a schematic you can reorganize a schematic and then compare the netlist and parts and if they are different you broke something. You can generate meaningful descriptions of of changes. Changed all the parts of this type to that type. Renamed these parts to these new names.
Problem is no one designs languages to be able to do that.
As a note, in Scala, scalameta will do just that and then dump out a structured view (in a specified protobuf format) of your code which you can work with.
There are other problems, anything more than naively comparing and diffing AST's is a hard problem. I've also seen some really bad things with editing non text data. Like the file you've been editing for a few days is corrupted.
And I don't see why you can't do this sort of thing with most languages that we already had. Indeed, this immediately reminded me of structured code search in IntelliJ IDEA, which has been around since early 00s. What's special about C# in that regard?
Not unique but far as I understand you can parse a C# module without knowing anything about it's dependencies.
> There's nothing wrong with Unicode text as a serialization format, so long as all your diff tools operate on the deserialized graph.
The point is you need to actually edit the de-serialized graph not the Unicode expression of program. Changes to the code aren't expressed as changed to the text, they're expressed as changes to the graph.
AKA diff is object foo nenamed object baz. And that's it.
And you don't have to edit the graph. You can still edit the serialized representation directly. So long as you diff the graph, how the changes were made doesn't matter. For example, there already are XML and JSON diff tools that do advanced structural diffing, and they don't care how that XML or JSON was edited.
I think your suggestion is most useful for making code review easier. It's annoying to read 5 commits to understand a change versus just one.
But then, my linguistic instincts are probably all slightly off: I have so far never gotten used to pull request not meaning 'kindly asking permission to download some code from your repo'. I really feel Linus should have consulted me on that one.
When I merge changes from someone, the commits are always imperative. If there are two approaches taken, say "Use <method a> to foobar" and "Use <method b> to foobar", then the imperative case makes way more sense.
From my perspective, picking a commit to my preferred method is very wonky when it says, "Used <method a> to foobar".
While the past tense makes sense from the author point of view describing what just happened until they typed `git commit`, I'm in the "present" camp since I find it more relevant to me when reading `git show <rev>`: it tells me what the commit is doing at this particular point in history. I don't really care about the programmer/author centric point of view at the time the message was written.
> it tells me what the commit is doing at this particular point in history
When I talk about a particular point in _history_, I use past tense. :)
... which makes past-tense release notes "team-centric". In other words, past-tense release notes are about justifying the work that was done (like some kind of work report), rather than being an exhaustive list of changes in the application behavior brought by a new version.
> If commits are written in the past tense and from the user's point of view they can be used pretty directly to create the release notes.
Bad idea IMHO.
Making developers worry about their commit messages potentially being used "pretty directly" as release note lines seems dangerous:
- It implicitly convey the idea that commits and release note lines should have the same granularity. This might be true in some cases for programming error fixes, but it's generally not for features.
- What about confidential stuff? commit messages are going to get a lot less informative if there's technically relevant stuff that programmers can't mention anymore (like the names of other customers, the yet-to-be-announced next product, etc.).
When you read a novel written in the present tense, you don't assume it tells a story that is currently happening right? ;)
As a result, some of my projects have a mix of differently-tensed commit messages, e.g. ones starting with "Fix..." and "Fixed...", etc.
My understanding is that pull request is a GitHub-ism. What git itself has is `git format-patch`, which does exactly what it says on the tin.
It is, but git has a command called request-pull[1]. Linus Torvalds has said[2] that certain aspects of the Github pull request process are not suitable or make it very difficult to submit patchsets for review for the linux kernel and that they should have followed the implemention used in git-request-pull instead.
[1] https://git-scm.com/docs/git-request-pull
[2] https://github.com/torvalds/linux/pull/17#issuecomment-56546...
You are right, of course. Idioms are eminently slip-upable, especially - I would guess - for someone coming from a closely related language with many fixed expressions beguilingly close, just not quite as close as they may sound on first hearing.
The article mentions the use of line-length and commit-templates. Personally, I have my .vimrc [0] configured to handle columns for commits (50 for the title & 72 for the body). Then, in my .gitconfig [1] I set a template [2] to be used for all commits. It's a relatively minimal addition, but it's improved my CLI experience with Git immensely.
[0]: https://github.com/Pinjasaur/dotfiles/blob/89ca76eaaef24165e...
[1]: https://github.com/Pinjasaur/dotfiles/blob/89ca76eaaef24165e...
[2]: https://github.com/Pinjasaur/dotfiles/blob/89ca76eaaef24165e...
Edit: fix link formatting
[1] Like my boss tomorrow. Or me in 6 months.
How much time do people spend to put too changes they did almost at once to make the code compile or the tests pass into two commits?
Much more valuable are larger commits at the size of a small PR.
Having the git blame output of the line I'm changing is very helpful when determining the potential consequences of changing that line. If the history doesn't matter, then why bother with commit messages at all. You could essentially script your editor to run "git commit -a --allow-empty --allow-empty-message" every time you write the files to disk.
So the main action happens outside of git. Maybe for other workflows git commit messages are more important.
Comments become stale and will often not be updated as the code changes.
So even if people are conscientious about reviewing comment changes (and absence thereof!), too this often gets missed.
Just use common sense: Be clear, be informative, don't waste people's time. You're not writing deathless prose or trying to craft the Greatest Commit Comment of All Time. The Grammar Police are not going to break down your door with their milspec copies of Strunk and White and put you up on charges.
One thing I try to do is be a little entertaining. Just little things, a twist of a phrase or something that might cause a commit to stick in someone's head for a while. I've had comments like "Best commit logs of the project," so at least people were looking forward to reading them. Which, if you are scientific and dry and oh-so-grammarly-correct, they won't be.
I've had people mention some source-code comments I'd made a decade or two earlier (e.g., in public headers). That was fun.
Think of commits like little emails. They have a subject that should fit in a subject cell of a table. They have a body. And they have attachments (the diffs).
Why wrap lines? Because it is text. If you feel every client ever created handles wrapping appropriately then I’d ask to move the rock you’ve been under. For 30 years I’ve watched client after client screw up text wrapping. Heck, just sample a few government websites. By claiming commit messages are text you are taking back control of the crazy cesspool that is the modern app era and crafting a prose and typesetting fit for your own high standards.
As Steve Jobs once quoted: “Be a yard stick of quality. Some people aren't used to an environment where excellence is expected.“
In fact, git has a command[1] to convert your commits to email messages.
I think what I really like Angular's Commit Message Guidelines that suggest you include a "type" (build, docs, feature, fix, refactor) prefix into the commit message to help organize at a quick glance what the commit does.
https://github.com/angular/angular/blob/master/CONTRIBUTING....
Here are some other resources
Erlang https://github.com/erlang/otp/wiki/Writing-good-commit-messa...
Gerrit https://www.mediawiki.org/wiki/Gerrit/Commit_message_guideli...
The document is translated into two other European languages, but the examples are still in English, which is a shame. A translator who is keen to go the extra mile would provide the examples in English and the target language, in my opinion.
I’d argue that central storage (somewhat ironically), open source support, CI automations (esp. web hooks), issue management, etc offer far more value.
In other words, GitHub (and friends) are the value worth spending time in, rather than being in the weeds of using Git “perfectly”.
It breaks muscle memory. For me, `git commit` is something that happens frequently - on the order of several times an hour, and not necessarily only in a single project. If the steps to commit are different from project to project, that's a mental speedbump every time I make a change, which pulls me out of flow and distracts me from whatever it is I'm doing. This is made worse when the commit format rules are in flux, because I then get tripped up within a single project.
Lastly, it's Yet Another Thing That Can Break(TM), and a specific example of that pernicious class of Technical Solutions To Human Problems.
You don't need to use commitizen to write the commit, if you want you can choose conventional commits and write directly git commit, or use nothing. But if you use conventional commits, later you can use `cz bump` and detect the type of increment, and there are already tools that help you create a changelog as well.
I'm using this stuff with some friends in a project we are working on, and we use conventional commits (whoever wants uses commitizen) for our git messages, and then after a PR is merged into master we can execute `cz bump` in our CI and we have a new relese ready to deploy.
TL;DR what commit type to use for css and what if one commit seems to fit for multiple types?
Full story short, think about your public, and ask yourself: - Am I introducing a new feature to my users? -> feat - Am I fixing something, with no new functionality? -> fix - Is my change breaking the API for my consumers? -> add BREAKING CHANGE to the body of your message, no matter what prefix you are using.
This 3 map closely to semantic versioning and are used in conventional-changelog.
MAJOR -> BREAKING CHANGE MINOR -> feat PATCH -> fix
Now, sometimes, this 2 prefixes might not be enough to describe what you have done. Maybe you introduced a new ci, that's no code, doesn't need to use one of the aforementioned prefix, so you use one of the optionaly proposed Angular prefixes (I think conventional commits is based on angular originally).
Sometimes fix might not be good enough to describe what you changed, in that case you can use `perf:` or `improvement`, but remember that this changes should not introduce anything to your consumers, let's say you converted a sass code that was too repetitive into a for loop.
TL;DR: use feat and fix, they map to semver and you can generate the changelog automatically.
Examples and more info: - https://github.com/angular/angular/blob/22b96b96902e1a42ee8c... - https://github.com/conventional-changelog/standard-version - https://www.conventionalcommits.org/en/v1.0.0-beta.4/#about
Hope I was helpful, Regards!
is a useless commit message. I should not have to manually open the commit to find out what was actually changed. The message should specify changed X to a. If it's too long, that's what the git commit description is for.
The keywords are also redundant. I don't need to see doc) if the rest of the commit message reads "update README". That's obviously documentation.
"style: black to files"
??? all that was changed was styling here with newlines and quotes. [0]
---
To be frank, it's not that hard to write a good commit message. It just requires you to use your brain for more than .2 seconds to write a good, concise summary. Forcing yourself to do this also in turn makes you write better (concise, focused) commits instead of just shutting off your brain and following some tool.
[0]: https://github.com/Woile/commitizen/commit/9cecb9224aa7fa68d...
The prefix on the commit has the benefit that you can parse it and use it for something else, like to generate the semver, this doesn't mean you have to use conventional commits, but any convention.
With commitizen you can make your own rules, and make it easy to share with new colleagues, it's better than pointing to a useless confluence lost in space and time, that was my idea at least.
https://github.com/angular/angular/blob/master/CONTRIBUTING....
But if you want to compare, I also dislike how they choose to expand the line width to arbitrarily accommodate certain git web uis but shun minimum terminal widths.
The reason for the 72 rule is that minimum terminal columns (since the beginning of time) is 80. git-log will pad the message with a 4 space margin, so to keep it centred you want it to be 72... alternatively to keep it from sprawling to illegible lengths you want to hard wrap it at about that width anyway.
So you will find one of 2 undesirable things happen if you don't hard wrap to this length:
1. Your terminal or pager _will_ wrap the text, but knows nothing of the formatting, so it will wrap onto the next lines without indentation (this does reduce legibility, making it harder to see where one commit ends and another begins in the full log).
2. Your terminal or pager _wont_ wrap, in which case have fun scrolling to the right - a lot.
You could rightly argue that if the terminal + cli + pager and git were one monolithic UI, then it would have a more holistic view of whats going on and smarter decisions could be made - but then we lose all the benefits of those separations (the unix way). There is no win win, but it is at least pretty trivial to hard wrap text automatically in your editor.
I have this habit since then and format all my git commits that way, despite the multi-line tradition in git.
Was Subversion wrong?
That's like a health guide listing: Circumcision, Limit coffee, Exercise, Vitamins, Avoid "Russian roulette", Vaccination, Brush teeth.
Q: What does the commit do?
A: The commit <commit>.
Q: What does the commit do?
A: The commit adds extra padding to the header.
When applied, this commit will <refactor abc controller>.
This commit <refactors abc controller>.
I personally prefer imperative because when you look at a commit it hasn't necessarily been applied yet. But it's like arguing about the difference of potato and potato. As long as you're consistent (and write good messages in whatever style) it doesn't really matter.