> Commit messages are probably one of the worst places for documentation They're a bad place for documenting the repository for users. They're about the sole p

> Commit messages are probably one of the worst places for documentation They're a bad place for documenting the repository for users. They're about the sole place to document what's in the _commit_... > and a common source of bikeshedding. You can bikeshed anything if you like. But I'll grant the author's claim that bikeshedding the exact format convention of commit messages is excessive. If someone wrote "Added feature X" as opposed to "Add feature X" - yeah, that doesn't really matter. On the other hand, if the first line of a commit message is extremely broad and vague, this makes it difficult for the developer browsing the commit history in a one-line-per-commit view. > Adding in information about what files have changed doesn't make sense It can makes sense if it's essential to the commit, e.g. "Moved `foo` from `file1.h` to `file2.h`". But TBH - this is bikeshedding. > this information is more easily stored by looking at the diff Ah, but the whole point is that you want to _avoid_ looking at the diffs of many commits. > Information about why and how often have better homes. Nope. > There's the code review history, the bug tracker These are not part of the VCS commit history, and may not even exist at all. > the code comments So, we want to put commit comments as actual comments now? No. > and the actual documentation. No. The actual documentation is: 1. Intended for users of the repository rather than developers/maintainers of the repository. 2. Documents all commits up some release (or up to some commit). > Your commit message essays will probably be lost or munged anyway – squashed, merge committed, or rebased. So will our code... but the point is that, after such squashes etc., there is still a commit history for which it is important and useful to have commit messages.