Hacker News new | comments | ask | show | jobs | submit login

Love #16 and the associated article. I cringe when I see something like "js fix" as a commit message.

However, not on board with the hate for rebase. If it's your feature branch and you aren't sharing it with others, I'd much rather get a cleaned up PR than one filled with junk commits because the author was afraid to rebase.




Nitpick with #16: I don't like when there is no "why" associated with a style rule. I'm speaking specifically to #3, "Capitalize the subject line". Why is this preferred to not capitalizing a subject line? Is there a reason, or is it an arbitrary decision (which would be fine - sometimes a style decision is, "We need a standard, and we chose this one." But I think the author of the style guide should explain that that's what they're doing).

But in general I liked the article. It's under-appreciated how helpful a good commit log is.


Capitalize the commit message because ...

Sometimes commit message deserves to be moderately long, like a paragraph or more. If one did not reference a code review or issue tracker link, for example, the need would likely be common. Even with an issue tracker there's value in capturing a few sentences of detail and sometimes more in the commit.

By capitalizing the commit message, it is natural to extend it from a single sentence phrase to a paragraph with an introductory sentence. I think of commit messages as analogous to JavaDoc where the first sentence or first line is taken as the subject, or like a document with a heading. It would be silly for short commit messages not to use capitalization while long do. A capitalized message works as a short description of the intro to a paragraph. Generally. once you're writing more than a single standalone sentence, capitalize. In a permanent medium where it can be either one, also capitalize.

A capitalized sentence or sentence fragment works in many contexts, like within a document or email. It would be annoying to convert going back and forth. Lastly, commit messages can sometimes act as names or proper nouns, and capitalization reinforces that role. Capitalization looks better as project or item headers in an issue tracker, and so to the extent that commits follow items, it's nice to consistently capitalize.

Capitalize commit messages because when Git tools generate commit messages, they generate capitalized ones. (Be consistent.)

I grok not capitalizing IM or IRC or other chat conversations, though I do if I start writing messages longer than a sentence. For everything but IM, capitalization constitutes the norm and good professional style.

This rationale might not be entirely satisfying, because why does English have capitalization to begin with? That's a linguistic question I don't know the answer to. However, I do know that the norms that lead to sentence capitalization also apply to commit messages and code documentation Not capitalizing them feels like refusing to capitalize any other writing: a potential distraction from the content.


Most of my commits start with a component name prefix and a colon. I don't capitalize those. I still write literate English commit message bodies.


That sounds reasonable to me.

  foo: Add utf8 support
If the component name is conventionally written in lower case, because it's a technical term, then I think a comment written in this way counts as good style. I might choose to capitalize Foo myself, but I think foo is defensible in that context.


I use this template and find my commit messages are much more useful now:

    # If applied, this commit will...
    
    # Explain why this change is being made
    
    # Provide links to any relevant tickets, articles or other resources


I like to write my commits in the Angular conventional-changelog format [0].

In particular, it looks like this:

    <type>(<scope>): <subject>
    <BLANK LINE>
    <body>
    <BLANK LINE>
    <footer>
Where `<type>` is the type of change (e.g. `feat` for a feature or `docs` for doc updates), `<scope>` is the scope of a change, `<subject>` is the subject line, with the first letter uncapitalized, `<body>` being an explanation of the change in imperative, present tense, and the `<footer>` containing information about breaking changes and any issues the commit closes.

I like it because I find that adhering to this style lets me have a nice seat of easy to read commits which explain their purpose and scope clearly.

Also, it lets me use a tool like `clog-cli` [1] to generate pretty changelogs [2] automatically!

The only nitpick I have with this style is the fact that they recommend not capitalizing the first letter of the subject line. This means that, for example, in emails or when creating a PR, I have to capitalize the summary so that it looks correct. Minor, but annoying.

[0]: https://github.com/conventional-changelog/conventional-chang...

[1]: https://github.com/clog-tool/clog-cli

[2]: https://github.com/clog-tool/clog-cli/blob/master/changelog....


Capitalizing the subject line makes commit logs much easier to read in my opinion. There's a reason we capitalize letters at the beginning of sentences


But it's not the beginning of a sentence. It's supposed to be a continuation of the implicit phrase "When applied this commit will ..." In which case capitalizing makes no sense.


> It's supposed to be a continuation of the implicit phrase "When applied this commit will ..."

No: it's supposed to be written in imperative form. For those of us who are not linguists, it's easiest to explain this as a continuation of that phrase. However, it isn't a continuation. It stands on its own.


If you're working alone in a branch, or a personal project it's not as big a deal... especially if you're going to squash before a PR/merge upstream.


I would be cautious about getting into the habit of squashing lots of changes together into one commit before sending upstream. It makes git bisect harder. Squashing is fine, but I suggest preferring several commits of logical units of change over one commit for a whole feature.


Agreed, rebasing also makes it much easier to find the set of commits you've added to your feature branch if the main branch is high volume.


> Love #16 and the associated article.

I can't recall where now, but I remember reading (and agreeing with) an article which proposed a slightly different format - describe what the commit did. "Fixes the js typo on the foo page".

Grammatically, I prefer this method as well, since the commit has already been applied, so it's not "going" to do anything; it's already been done.

Of course, the only difference is in the tense of the leading verb, so it's probably one of those "potato" thing.


I thought git commit messages were supposed to be present tense. "Fix the JS typo on foo page for Chrome."


Well, especially if you take the source article to heart, "Fix" is actually future tense - "When applied this commit will fix the JS typo on foo page for Chrome". "Fixes" would indicate the present tense: "This commit fixes the JS typo [...]"


I read it as using the imperative mood, myself; otherwise the sentence is missing its subject.


I've seen that reasoning as well, but who is doing the telling, and to whom?

Ain't English fun?


If the sentence still makes sense when ", dammit!" is appended to it, it's in the imperative mood and you are the subject.


Fair enough, but how does a command apply to a git commit? If it's telling the git commit what to do, that doesn't make sense, since the commit comment is supposed to be about the commit, not a command to the commit.

If it's telling me what to do, that doesn't make any sense either, since the work's already been done; the results of doing that work is the commit.

I guess it could be considered to be an abstraction of what request initiated the change, but what value does that provide when going back through git logs (when compared to a past or present verb tense that describes the changes)?


I think the actualy reason for the choice of tense is brevity. Fix is three characters fixes or fixed is five, similar for update vs updates/updated, add vs adds/added etc.


Taking this opportunity to promote gitlint, a git commit message linter (and hook) I wrote in Python: https://github.com/jorisroovers/gitlint




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

Search: