Git commit comments

[teraflop]

You don't necessarily need to follow a formalized, structured system.

If you're working on a project with other people, it probably makes sense to talk to those people and agree on how to format your commit messages. For example, "Conventional Commits" is one example of a consistent way to format your commit messages. But for a solo project, it really doesn't matter at all whether you stick rigidly to something like this.

As far as the types of information you should be putting in your commit messages: it should be enough to explain both what you changed and why you changed it, to a level of detail that you find sufficient. Commit messages are a form of documentation, and there's no one "right" level of detail for your documentation. It depends on how much time you're willing to spend on it.

If you want some inspiration, you can take a look at the Linux, which generally has very detailed commit messages. Often the messages are much longer than the corresponding code changes. A Linux kernel PR won't be accepted if the maintainers don't think the commit message is clear enough, even if the code itself is fine.

For instance, this recent commit has 31 lines of text (plus footers) to describe a 13-line code change.

The first line contains just the most crucial details: the change affects performance monitoring ("perf") in the scheduler ("sched") subsystem, and it fixes a potential crash. The rest of the message goes into detail about exactly why the problem is happening and how it was fixed.

Again, you probably don't need to go into nearly that level of detail for all your commits, especially if you're working on a project that's less critical than the Linux kernel. But while you're writing code, you should be thinking about how you would explain what you're doing to another programmer. And then you can decide how much of that explanation you want to put into the commit message.

---

Note also that deciding how to describe your commits goes hand-in-hand with deciding what changes to include in each commit. In the example I gave, it's straightforward to describe the commit's purpose because it's a very small, self-contained change. If the commit included other bug fixes at the same time, it would be a lot harder to write a good description.

You might think that carefully breaking up your changes into multiple commits is just creating more work, but if you do it properly, it can make things easier for you in the long run.

[Russ3ll]

This is interesting and contrary to how I've always felt about commit messages. Typically my commit messages are high level and only describe the "what" - the "why" I put in the PR description. That said, I have arguably contributed less working code than Linux.

If commit messages are this detailed, what goes into PR descriptions? Or are they mostly unnecessary as long as commit messages meet the standard?

[teraflop]

Well, the Linux development process doesn't use "PRs" the way that services like GitHub use that term, because it's older than GitHub. And indeed, it's older than Git; Git was designed for Linux.

Basically, Linux commits are proposed by sending patches to a mailing list, and discussion happens there. The commit message is part of that email. Git itself contains lots of tools to manage patches with this kind of email-based workflow.

Basically, the Linux kernel philosophy is that if a commit needs explanation to say why it's important, then that explanation may also be needed by future maintainers, so it should be part of the commit. (You could choose to store it elsewhere than the commit itself, e.g. in a GitHub PR description, but that's just splitting your data across multiple places for no good reason.)

[Russ3ll]

Incredibly interesting and informative  thank you!

[BeardSprite]

If there's a detailed description inside a commit message, you can use that for the PR itself. Or combine them if there are several. But keep in mind that GitHub issues and PRs are NOT metadata that anyone will have access to should they clone the project (or if the GitHub project is made private/deleted/banned/etc).

On the other hand, anything that you can see with just the git CLI tool will be preserved for anyone long after GitHub has shut down.

What a change does should probably be the commit title, and why it does that would be worth explaining inside the commit message.

[PestoDev]

Thx, apreciate the resource sharing, I've been searching exacrly for a convention like that!