Hacker News new | past | comments | ask | show | jobs | submit login
Commit messages guide (github.com)
385 points by walterbell 31 days ago | hide | past | web | favorite | 183 comments

This is one of those interesting bits where things feel more like personality types as opposed to ways to create maintainable software. I have yet to see a project fail because commit messages were or were not in imperative form or if the first letter was capitalized. I have no problem doing it if someone in the team finds it important, and I have no issue if someone on the team does not do it.

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.

I don’t completely agree. By taking the time to write commit messages you are documenting your code at a fine-grained level. Think of it like a short email that explains to your (future) colleagues and future self what you changed and especially why you did 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.

> Think of it like a short email that explains to your (future) colleagues and future self

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.

Hmm, I think it depends on the case. Sometimes it's appropriate to leave comments on the file, while sometimes trivial changes don't need to be mentioned and explained only at a commit message.

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.

>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.

> 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.

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).

That actually depends on how it gets copied and pasted.

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.

I think a good way to look at it is to think of "explain why" in commit messages as explaining why the code was changed from the previous state to the new state. This may need explanations on how some of the code works, but it doesn't have to.

The "explain why" that explains how the current code state works however should sit next to the current code.

Yep, it’s definitely a thing to exercise technical-communication judgement about.

They're associated with a line with a file. git and other SCMs provide tools that allow you to see what commit is associated with a given line, what the state of the file was at the time the commit was made and when lines in that file were removed subsequent to that commit.

> 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.

The guarantee would be the same guarantee you get when you update a codebase: that you (and code reviewers) look at the nearby code and see if it still makes sense in the context of your change.

> 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.

... The answer to "why?" goes in the tests.

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.

Unrelatedly: `tig blame` is a better UI for exploring commit history than `git blame`.

To take the example from this guide

> 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`?

No because I would ask myself “Is this a description of why the end state of the code needs to be this way?” to which the answer would be “no.”

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.

Nobody questions it is important to write clear commit messages. The issue is being nitpicky about what exact form is being used like whether to capitalize first letter or not.

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.

I feel it reduces cognitive load, like proper formatting of code.

Do you enforce consistent code formatting in your codebase (using CI, maybe)? If so, why wouldn’t you do that with commits?

I used to be in the camp that cared a lot about formatting, but over time realized that it's more my OCD than any practical reason.

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 in that camp that doesn't enforce consistent styling in code or even particularly believe in the value of linting at all! ^_^

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.

Because the commit messages, just like email messages, isn't part of the product. They are part of communication between developers. You could as well require people on mailing list to never top-post and always spell correctly, to reduce cognitive load. Some people actually do that, but they are pretty annoying. :)

People absolutely do question if it is important to write clear commit messages. I've had quite a few conversations where people have said things along the lines of "why do you even care? no one ever looks at the commit meesages".

> The issue is being nitpicky about what exact form is being used like whether to capitalize first letter or not.

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?

If that's the case, why have standards when it comes to writing code, e.g. when to use camel case? Why have styles at all for writing in a language like English that tell you how titles should be formatted? Consistent format and structure reduces cognitive load IMO, because it breeds familiarity. Also, Git itself uses the imperative mood whenever it creates a commit on your behalf. Consistency is good.

Also it's a good litmus test for whether you really know what you changed. If you can't describe what you did in a couple of lines, you either did too much or lacked clarity.

I second that. I find that it helps junior dev find the sweet spot in commit granularity.

Commit messages are a poor place to document code because they don't stay with the code. If the code isn't obvious, comments work wonders and often make the commit message more focused on documenting commit history not actual code.

I agree that when writing confusing code, it is best to add a comment to explain it. However, in cases where the line isn't commented being able to `git blame` a section/line and read the commit message it was part of to understand the context for it can be invaluable at time.

That's a good point. I think git blame is underutilized in my world.

These are two different things.

A coment in code describes the state of the code as it is. A commit message describes a change in the code, a delta.

A comment in the code can do both, and it should. You should explain why your code is the way it is, not just what it does. Anybody can see what code does by just reading the code.

There's still a distinction between describing why the code is the way it is, and why it evolved the way it is over time. The latter is what commits capture.

Commit messages are great for explaining the order in which things happened and talking about changes that apply to disparate pieces of code.

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.)

> Commit messages are a poor place to document code because they don't stay with the code.

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.

They stay with the code as long as the code is absolutely untouched, which often is a lot shorter than a comment about code remains relevant. Code gets moved, reformatted, ... without details about it becoming stale.

Unless you have large chunks of code moved around wholesale, you can usually track all commits that touched a particular line of code. I've done that while debugging codebases that were over a decade old. And seeing those commits was incredibly helpful, despite the code itself being heavily commented.

> I have yet to see a project fail because commit messages were or were not in imperative form or if the first letter was capitalized.

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.

I have yet to see a project fail because commit messages were or were not in imperative form or if the first letter was capitalized

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.

> 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.

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...

Isn't this what

    git commit --amend --no-edit

Another, very popular "personality trait" I see is people that have to constantly upgrade and replace tools and frameworks for minute or unknown benefits. This instead of asking themselves, "What is absolutely the best use of my time that will bring most benefits to the project?"

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.

Sounds to me like someone looked at the production failures and declared "These failures are due to technical debt and poor code quality. What can we do to fix that?"

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 (setup oversight and monitoring, understand underlying problems and their impact, prioritize, 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.

Political players will use these things to gain power and benefits. They will get someone fired because the bike shed had a minor issue, and meantime will get everyone to ignore the power backups to the power plant.

1000 times this. There is also a significant drawback to having to much rules about commit messages which is that it can lead to horrible passive aggressive behavior: "Dear XYZ, I have undone your commit abf9de because the commit description was improper. In future, please follow the guidelines found at http://ABC. It saves work for all of us. Thanks in advance."

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.

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.

Generally speaking though, I rarely care about reading multiple commit messages at a time. Outside of a PR (where to be honest, I'm far more interested in the PR description than the individual commit messages provided they're not something horrible like "changes"), I generally only look at commits in the context of a blame, which means I really need to understand one commit in isolation.

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.

Well, then you can go and prove that. :) Because the lack of evidence in either direction (wrt cognitive load and commit messages) points us towards the null hypothesis. In my own experience, fixing bugs in C code long abandoned by the original authors, it doesn't matter one bit if the commit message reads like a novel or literally just "fsjdlkfdjlsfl fskjl". All that matters is the change is self-contained and references bug tracker ids and mailing list discussions.

Also in my experience, passive-aggressive power trippers love anal retentive rules. Hence adding more than necessary carries a significant risk.

A simple rule of thumb to prevent this: if it made past code review, it stays, because, by definition, nobody cared enough to notice it and/or call it out.

(This goes only for style guide violations, of course, not behavioral changes.)

>I have yet to see a project fail because commit messages were or were not in imperative form or if the first letter was capitalized

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.

This is no different to coding conventions.

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.

> I have yet to see a project fail because commit messages

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.

> 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?

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.

You can remove all tests and the program will still work fine.

This is the start of a Strunk&White-level style guide. There are reasons for things beyond what the OP goes into; for example, the imperative form in English is also the infinitive, which is the most basic form of the word and the one that someone ESL would know or could easily recognize and look up ("caught exception" vs "catch exception"). This is consistent with wording your bug report titles the same way.

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.

Agreed, I think too many people assume their code will live in their small team forever and ever. When you have a few thousand people committing daily it's a different story you need to keep consistency high and the jumping between past and present tense is gnarly.

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.

> This is one of those interesting bits where things feel more like personality types as opposed to ways to create maintainable software. I have yet to see a project fail because commit messages were or were not in imperative form or if the first letter was capitalized.

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.

The repository does not follow its own guidelines.

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...

I heavily dislike the hard wrap requirement. Why do that if our clients could do it nicely, based on screen size, preference and everything?

Because very often the client will be some piece of command line tooling that doesn't do those things.


> 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.

The terminal will still wrap that long 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.

Maximum flexibility with minimum complexity. You want lines that wrap because humans are going to read the message. But you need to be able to not wrap when needed, e.g. when posting code snippets. You need something that any client (including email clients written 10 years before git was a thing) is going to recognize and know how to display correctly. Hard-wrapped plain text fits the bill.

Why would you need to support a commit message in a 10 year old client? This is like saying you need to support IE8 in a web app. If the person doesn't like things being broken, then maybe they should update there software...

> 10 year old client

Or simply using a terminal with multiple windows open. I hard wrap at 50 chars and I haven't died from exertion yet.

The ability to display commit messages nicely probably is not the metric by which people chose their email client. Wrapping text where it makes sense is also a task which is best done by the human writing it. I'd rather have a meaningful text flow with sense than some machine hard wrapping in the mi dle of the sentence.

> Why do that if our clients could do it nicely, based on screen size, preference and everything?

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....

Let's do markdown in commit messages then. I despise hard wraps everywhere I see them, they work so bad.

Would those relevant points not include the quote about using imperative style? "Header line: explain the commit in one line (use the imperative)"

I don't think the grammatical structure of the sentence matters too much, the important part is "explain the commit in one line".

What I like about Linus's summary is that it articulates which use cases matter; "here are the tools I am using, make my experience pleasant."

Use the same spelling conventions as the auto-generated messages seems a reasonable request.

Or look to git's repo itself for examples:


That link also says "(use the imperative)".

But it does seem like Linux is inconsistent about capitalization. https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/lin...

> That link also says "(use the imperative)".

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.

A sentence must have a subject and a predicate, and a verb in the infitive form can't be a predicate (it's usually going to be some kind of complement). 'Fix the bug' is usually taken to be a sentence describing what you meant the commit to do, which is why the imperative is the more likely interpretation.

> A sentence must have a subject and a predicate, and a verb in the inf[in]itive form can't be a predicate

In the well-formed sentence

    For cyanide to kill you, you need to be exposed to a lethal dose all at once.
What do you think "to kill you" is?

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.

> What do you think "to kill you" is?

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.

"For cyanide to kill you" is constructed from the sentence "cyanide kills you", and obeys exactly the same rules. It predicates an action (killing) of a particular agent (cyanide), though it is not bound to any particular time. If "kills you" is a "predicate" in the finite clause, then "to kill you" is also a predicate in the nonfinite clause. Can you make the argument that it isn't without special pleading?

The infinitive form of verbs in English always starts with "to", as in "to add", "to fix" etc. That would be a very strange commit message. Imperative is normal: "Add x feature" etc

This is not correct; many infinitives are marked by "to" and many aren't. Such marking may, depending on context, be required, optional, or prohibited. For example, in "this can be a hassle", "be" is an infinitive. There just isn't any way to interpret it as an imperative. Who are you commanding?

And in the commit message "Add feature X", "add" is likewise an infinitive.



Eh? "To be" is not the main verb in that sentence so of course it's in infinitive form. "Add feature X" is imperative. "To add feature X" is infinitive.

> "To be" is not the main verb in that sentence ["this can be a hassle"] so of course it's in infinitive form.

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.

I thought it went without saying that we're talking about main verbs because verbs in other positions don't change forms anyway.

    At this point, he has been being investigated for six months.
That sentence contains four verbs, of which zero are in the plain form. (One is present-3sg, one is ING-form, and two are EN-form.)

Are all four of them "main verbs"?

While I've naturally gravitated toward the "capitalize and use the imperative," I've never been down with the "good commit messages are 50 characters or less" mantra. Why 50? Is there an important tool that breaks if my commit message is 55, 60 or even (gasp) 70 characters? Is there a real case to be made that "Add total vocab entries per capsule limitation" is a good commit message that becomes an utter irresponsible trash fire if one spells the entire word "vocabulary?"

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 completely disregard this rule. I find it much more helpful to be able to include more context in the message (even the first line).

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.

The 50-character limit is not a hard and fast rule for me, but one case in which it is useful is when having your editor display the most recent commit message next to every line - the sidebar only has limited width, otherwise I can't read the code in question.

The commit header becomes the email "Subject:" line. 50 characters is less than 72, and allows for the inevitable "Re: Fwd: [Re:] Re:..." mess of email threads, without losing context.

Is that the reason? So if your commits aren't getting emailed anywhere, you can ignore this rule (within reason)? I would think only a small minority of git projects have email notifications enabled.

Several ways to display the history, like "git log --oneline", or versions thereof that include the author and date, do profit from short head lines.

But "For long commit messages, give a summary in up to 50 characters first" solves that as well. There are good reasons to use longer commit messages:

* 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.

Of course. Noone here said that the commit header shouldn't be followed up by a more detailed description. "git log --oneline" displays only the commit header.

Maybe you're mostly referring to some more complex use of --oneline, but to me that seems like more of an argument for not editing useful information out of your subject line to fit the character limit. Of course all other things being equal, a short subject line is preferable to a long one. But if you have to make a choice, I think it's often better to treat the character limit rule as a guideline.

I'm sure I've broken this rule many times, and I'm not aware that it's ever caused a problem.

Of course. It's just a guideline. All I've done is given a justification for the guideline by presenting a common usage scenario (as intended by the authors).

Or wide terminals.

Everything profits from wide terminals, except the user who has limited screen space. (And while you can in theory buy more screen space, turning your head all the time has a large cost)

It's the original reason the rule was created. There are other reasons which justify sticking with it.

I don’t think that this guide is focusing on the important stuff. It’s advocating really minor things like the capitalisation of the first letter and the use of the imperative form while it completely ignores the most important rule for a commit message: Add the Jira id (or whatever issue tracker you are using) in the commit message. In this way when doing a blame on a file it’s immediately clear why something has been done in that way, with a in-depth explanation of the use case just one mouse click away in the issue tracker system. For me this is much more important than capitalising the first letter of the commit since it provides an immediate and durable value.

> most important rule for a commit message: Add the Jira id (or whatever issue tracker you are using) in the commit message.

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.

Obviously it’s a possibility, but in my experience, in the several jobs that I had in my life I experienced 1 or 2 source control migration in pretty much each of the places that I have been, and a grand total of ZERO issue tracker software change between all of them. It’s obviously anecdotal but pretty much everyone is migrating to git, changing issue tracker is something that you experience much less. And even if it happens a proper migration would preserve the ids, so nothing is lost if it’s done correctly.

I think the most important thing is to create atomic commits. Each commit should do one thing and do it cleanly. In other words, if you later regret the change, you should only have to revert one commit to remove it. If when reverting you need to go back and reapply part of the commit (due to it being unrelated), that's the sign of a bad commit.

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.

When you are trying to merge a commit to a branch, and it wont merge cleanly because of some trivial white space change someone made in an unrelated commit, you will understand why people dislike it.

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.

The other reason is that it all shows up in history of the affected lines of code. Much later, when I'm looking at a line, and I see git blame saying "Fixed ...", I have to go look at the commit to figure out why it touched that line - and having to spend that time only to find out that the only effect on that one line was replacing two spaces with one is wasteful. When it's a separate commit with a clear message that says it's formatting-only, you can just skip it.

Wouldn't it be nice if git had an understanding of what was being committed, and could identify white-space/formatting changes versuses substantive changes? I suspect it could automatically fix these types of common issues.

Then Git would have to be content-aware, as sometimes whitespace is meaningful and sometimes just formatting.

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...

> Then Git would have to be content-aware, as sometimes whitespace is meaningful and sometimes just formatting.

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.

I've dealt with tracking schematic capture and layout software. And just a infinitesimal amount of database stuff. The difference I note is that software version control systems are hopelessly broken because they work on text and not structured data.

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.

The problem is that to properly understand the structure of the code you need to load in all dependencies of the code (both in other files and imported third party modules). That's time consuming and has to be done somewhere.

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.

That why I said a problem is languages aren't designed with that in mind. I think C# is pretty close since it was written with debugging as first class feature. But to really get the benefit you need a language that's tightly coupled to refactoring tools. And that means giving up on Unicode text as the file format.

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.

There's nothing wrong with Unicode text as a serialization format, so long as all your diff tools operate on the deserialized graph. I mean, when you do a diff on a database, do you care about the binary format of its files on disk?

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?

> 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.

Most languages can be parsed without knowing dependencies of a translation unit. I would say that something like C and C++ (where you need to know if something is a type or not in many contexts) is an exception to that rule.

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.

This is subjective. Sometimes your change has to touch other things in small ways, that other code then depends on over time. Even if your project tries to avoid this, it'll happen to any big or old enough code base.

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.

If your change must touch too many other things that may be a sign of tight coupling. Not a good sign. Maybe it would be good to think about splitting things apart as a separate lib, or service. Then you'd be able to make small, safe, changes that are atomic.

Decoupling is not free (especially long term, because it creates a new boundary), and when you decouple without any particular reason to do so, you often end up with more complicated code to do the same thing.

That's a fair point. Thinking more on it, you're right it is more about making reviewing old commits easier.

This is strictly my own idiosyncrasy, I know, but it has stubbornly refused my many attempts to change it over the years: I cannot get used to the imperative. Do this or do that always signals some pending issue, something yet having to be done. Whereas a message saying did this or did that tells me exactly what I need to know, namely what the commit was about in the first place.

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.

Imperative makes way more sense when you're a maintainer and for people forking, etc.

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".

Past-tense is about the what the programmer did to get to the patch, present (imperative...) tense to me is describing in the absolute what is a diff is doing (it describes the act of `git am` this patch).

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.

Past tense is not necessarily programmer-centric. Release notes are generally written in the past tense (with headings like Added/Changed/Removed). 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.

> 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. :)

> Past tense is not necessarily programmer-centric. Release notes are generally written in the past tense (with headings like Added/Changed/Removed).

... 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.).

Why do you think release notes are "team-centric"? Who do you think release notes are for?


> When I talk about a particular point in _history_, I use past tense. :)

When you read a novel written in the present tense, you don't assume it tells a story that is currently happening right? ;)

The simple rule is to pretend all commits start with "once committed, this change will ..." Or more simply, "this will ..."

I feel the same. For personal projects, unless make a conscious effort, my natural tendency is to use past tense.

As a result, some of my projects have a mix of differently-tensed commit messages, e.g. ones starting with "Fix..." and "Fixed...", etc.

I no longer worry about verb tense, simply using whatever sounds best to me when writing that particular commit message. My messages don't match each other, but so what? They're readable and to the point. Why waste time worrying about something that just doesn't matter?

By yourself it doesn't matter but when you work with teams it is nice to have a consistent style. It's like asking why we have style linters, brand guideline books, and so forth. They're not strictly necessary but it makes things more pleasant to work with. And it takes zero effort to use the imperative.

Imperative vs past is a stylistic issue and in the end doesn't impact how the commit message is understood.

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.

> My understanding is that pull request is a GitHub-ism.

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...

Didn't know about request-pull, thanks!

I find Scandinavians are much better English speakers than they give themselves credit for (they are sometimes deeply apologetic about immaculate English). Idioms, however, are the hardest part about any language and in English they are hard to nail without painstaking dedication to that language, to the exclusion of native speech in other languages. And that's how you get idioms like pull request, or Ace of Base "All that she wants / is another baby". The latter is supposed to mean "another lover" but it conveys "another pregnancy".

Linus and I are equally Scandinavian, so please let me take this and run with it: The one brief, shining splitsecond of my life where I may actually have perceived something clearer than he did.

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.

Present-tense tends to be shorter (e.g. “add” vs. “added”). Past-tense phrases add characters that eat up space in a one-liner that might be used for other info.

I find commits very relevant when grokking unfamiliar codebases. The history and changes (plus, how they're documented) are half the battle for me in that context.

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

Yes! Someone unfamiliar[1] with the code-base should be able to make basic sense of what was done and why.

[1] Like my boss tomorrow. Or me in 6 months.

I don't know how people are programming. I have good unit tests and regression tests and even though I commit frequently, most of the time I don't end up with single purpose commits and usually when I trace back commit history these single purpose commits don't help me much, even if the team mates were writing commit messages like these.

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.

I don’t understand why the history of the code matters so much to some people. Give me well designed and commented (!) code, with tests, designed to be understood by humans. Thats a bar few code bases clear, if I need to look at the git history its a sign the code is crap and I have to use all the information that I can get, with history being my least favorite because it has shitty UX (discoverability, navigation).

As time passes, practically no actively maintained codebase is going to clear your bar. It's going to pass through several different teams, with different policies and standards. Eventually, parts of it are going to be put on life support, which generally means an understaffed team that scrambles to patch up the most egregious bugs, often with dirty hacks, because they have no time and resources to do massive rewrites that are necessary to fix things properly. Maintaining such codebases requires a lot of "code archeology", and good history makes it much, much easier.

Not sure I get your point. People will cut corners and mess up the code, but somehow the history could be excempt from this?

Having properly separated and single-purpose commits is awesome when running `git bisect` [1] — especially with automatic tests. As well when you revert said commits after the offender is found.

[1]: https://git-scm.com/docs/git-bisect

If you're using a CI that runs on every PR/master merge wouldn't it catch this without the need for git-bisect?

Only if your tests have perfect coverage. And by "perfect" I don't mean lines or branches, but program states.

> I don’t understand why the history of the code matters so much to some people.

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.

Our workflow is: - branch - commit first version, open Github PR with a text describing the PR, which is usually longer than the git commit message and contains links to notion pages and other things detailing the design - reviewers look at the code, and there is some to and fro with smaller commits until the PR is fine - code gets merged

So the main action happens outside of git. Maybe for other workflows git commit messages are more important.

>commented (!) code,

Comments become stale and will often not be updated as the code changes.

This is what code reviews are for. Why would you exclude comments from that? It certainly doesn't happen in our team.

Comments often refer to stuff that's not directly in the "review window" i.e. the actual diff plus additional context you'll see in a typical code review setup.

So even if people are conscientious about reviewing comment changes (and absence thereof!), too this often gets missed.

Gahhh. Ignore most of that stuff about language, it doesn't add much value.

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.

I have been recommending this article to my teammates:


Agreed. This is by far the best guidelines for git commit messages I'v found.

I personally don't like hard wrapping the body of a commit message because it then looks terrible every where - GitHub website, git client etc. and it becomes much harder to read

That’s interesting, IIRC short lines are supposed to increase readability because longer ones are harder to mentally wrap.

Sure, but there’s no reason that has to be done manually. Leave it to the client.

Most clients don't wrap in a way that helps readability, though. Look at Hacker News comments for example. At 1:1 zoom the text is spread out across the screen in super-wide lines that are hard to read. The classic recommended 72-char hard wrap guarantees a good reading experience on all but the narrowest of screens.

I often browser HN in a half width window for this exact reason. To be clear, I don't fault HN for this; I can trivially resize my window to whatever works best for me. Commit messages are different because people often interact with them via command line based tooling.

What about parts of the commit messsage that shouldn't be wrapped and having them wrapped hurts readability? If you rely on soft-wrapped, then there's no way to prevent that from happening.

Look, the simple matter is that commit messages are designed from the bottom up to be a medium of prose in the same way email is. I would venture to guess that an email written with good grammar, capitalizes subject (that is less then 50 characters), and a articulated thoughts would ecstatically welcomed compared to the drivel we normally recieve. Commit messages are no different. If one feels that a one liner is sufficient to establish context because the code is so impeccable then that is nothing short of arrogance.

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.“

> 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).

In fact, git has a command[1] to convert your commits to email messages.

[1] https://git-scm.com/docs/git-format-patch

I have my own notes here: https://www.aizatto.com/engineering-code/commit-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.


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...

I can see the value in gerrit's suggestion of including the component name in the header. I'm not sure I see the value in adding the commit type. Where do you see it as useful?

The best advice that I got came from CodeSchool's github course (this was about 5 years back so I am not sure if they have updated it). It said that the commit message should indicate what will happen if that commit is applied by another user, not what changes have been carried out. It's worked well for me so far.

I think the form being used is "infinitive" rather than "imperative". The forms are identical in English, so it's hard to be sure, but in other European languages it would be the infinitive, I think, so I would guess that it's the infinitive in English, too. Also, it just doesn't seem like a command to me.

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.

The value of git is the tooling around pushing code to a central place. Version control is a relatively minor (albeit occasionally very helpful) part of the value of git.

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”.

I prefer conventional commits, I have created a tool that prompts some info to make it easier to remember, I can also bump automatically the version using the commits. I've been using it with friends with no issues. I really like how the commit log looks


I've seen real problems with using commitizen. The first, and probably most insidious, is that if you've got a tool to enforce a format, people stop thinking about the content, but still believe they're getting good commit messages because the tool tells them so. This makes it harder to convince them that content quality needs addressing. Worse, it gives you no flexibility to use the limited space in the commit header if you, the human, have a better idea of what the commit message should be than the tool has.

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.

Hey I'm sorry you had problems with it. I myself don't use it always. My main idea is to make it easier for teams to share the commit conventions with new developers (at work, for example, there was other convention which I find it hard, so I made a plugin also for it). Sometimes I'm not sure what type of change it is, so I can trigger `cz commit` and the prompt helps me remember what is what and to choose a proper prefix. My main objective was to avoid writing lazy commits 'fixed api', which I've seen around.

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.

I’ve been using git for almost a decade now and I don’t understand how conventional commits work. The docs make no sense to me: https://www.conventionalcommits.org/en/v1.0.0-beta.3/#specif... , full specification states there are only two types of them - fix and feat. Then they point you in the direction of https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING... and at this point I wasn’t even sure if there’s a golden standard or can I go with “anything: foo”? I really tried to use this methodology but as a front end had to push a lot of CSS changes and I didn’t know where they belong to, is it refactor if I change border color? Or maybe “style”? But according to the guideline style is for code styles like white space or missing semicolon but isn’t that refactor? I’m dumb maybe but I feel like it’s incredibly complex for such a small thing. If I move one Sass rule few lines up and the whole layout changes due to specificity changes - is it a refactor, new feature or style and what if it fixes a bug? :( Could you explain it to me? I’d love to stick to the naming once I get it, the profit seems to be quite big especially if in 10 years I want to let’s say parse and analyze my code. Thanks!

TL;DR what commit type to use for css and what if one commit seems to fit for multiple types?

Hey great thing you are interested!

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.


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!

Your commit messages don't explain why stuff is happening. That might be ok for a private git repo, but once you have different teams working on it over several years it's not good enough.

What do you mean? Feat, fix, etc. Those are all short, instantly understandable explanations of why a change was made. If you're looking for an explanation for why the code itself was coded a certain way, that's not what git messages are for. That's what comments are for. You're explaining why you made the commit, not why you wrote the code the way you did.

"refactor: changed stdout statements"

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...

Oh wow, it's good to have some feedback, I do my best to write something explaining what changed, and what would make sense for someone reading that is not me, I guess I have to try harder. I do not agree that the tool makes you lazy, I think it actually forces you to write something, I've seen many other popular repos (like requests) that don't follow any conventions and they have commits like "fixed stuff", "more changes", etc.

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.

I looked specifically at: "refactor: changed stdout statements" and had no idea why this has been done, what was the problem with it before it changed, how does the patch make it so the problem now gone?

What's wrong with Angular commit message guidelines?


Nothing - in the context of angular project, which this is not. They are not general enough, everything isn't angular.

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.

Shouldn't your terminal view be able to wrap the text itself before showing it to you? That seems a UI display issue rather than one to solve by changing the underlying data representation. I understand why that's not good with code but commits are almost always non-code.

You know what, that's a fair point, but it's also just not how it works...

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.

Subversion recommened commit messages to be single line, without breaks. The argument was that it's good for scripting, the one record = one line approach usual for unix scripts.

I have this habit since then and format all my git commits that way, despite the multi-line tradition in git.

Was Subversion wrong?

I read the following tutorial on the topic few years ago and it has really helped me with commit messages:


This guide is strange. The order of rules is in no relation to their importance: Imperative, Capitalize, Self-contained, Explain, Avoid "stuff", Length limit, Consistency.

That's like a health guide listing: Circumcision, Limit coffee, Exercise, Vitamins, Avoid "Russian roulette", Vaccination, Brush teeth.

Author suggests using imperative form commit messages ("add X") as opposed to past tense ("added X"). Past tense should be avoided, but using imperative form sounds unnatural and incomplete. I prefer present tense. Just follow this template and you'll be fine:

  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.
In this example, "adds extra padding to the header" is your commit message.

Both are natural, but imperative is simply more commonly used.

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.

When I look at commit messages its to know why the and who the . Note. Its still OK to leave comments.

I do not like the idea of giving anyone access to my email account. I'd rather see a desktop version of an inbox-clone.

Guidelines | FAQ | Support | API | Security | Lists | Bookmarklet | Legal | Apply to YC | Contact