Why I write commit messages

I usually focus on three things:

• What I'm changing: yes, this is technically described in the code, but if your change is more than a couple of lines, it puts a lot of work on the reader to make them figure it out from the diff, and that gets amplified if the reader is looking at multiple commits. And, the literal code committed won't necessarily have the impact you were trying to make, so it's helpful to describe the intent of the change.
• Context for why I'm making the change: the "why" is often harder to infer than the "what", so requires some description. I try not to just link to tickets, because again that puts all the work on the reader.
• Considerations for the reader or for code review: the risks of merging the change, gotchas, anything non-obvious that's worth highlighting. I try to make it explicit if there are parts of the change that I'm unsure about or don't understand well, or if I intend to follow up this change with further work.

I often format the message to show the what vs why vs other considerations separately, as this makes it easy to read at a glance, and it's also a nice format to copy straight into a PR description.

This is the kind of thing I'll write. I've made these up, but they're inspired by changes that I worked on in past roles:

Some of the more prominent commit message advice is based around formatting: writing in a particular tense, keeping subjects at 50 characters, bodies at 72 characters, etc. Personally I like to see that consistency, but it's not where the value is, and if anything it creates barriers to entry if you're dogmatic about message style. You have to pick your battles when collaborating at work, and as long as someone doesn't break standard git tools, then the part that's valuable is providing the information.

Even if nobody else read my commits, I would continue to write messages for myself. I will not remember every change I worked on in a few months, let alone a few years, so it's helpful to have those messages from the past. If I think my old code is terrible, then I can hit git blame or read the log for that file, and see that I articulated a particular reason for doing it that way two years ago – or more likely, see that there wasn't a good reason and the code really is just terrible. Either way it helps me make better decisions.

Another consequence of this is that reading a proper description jogs my memory a lot more than looking at a one-line link to a ticket number. Or, sometimes the reverse happens: a colleague will ask me a question, and I won't remember the exact answer but I'll remember that I worked on the relevant code change and I can find the answer quickly by grepping the git log.

Commit messages scale nicely, not just through time, but also out to a lot of people: the messages are useful for other engineers who don't know what was in my head when I made the change.

I believe there should be professional expectation amongst software engineers that we'll provide some context for our changes somewhere. There's nothing more annoying than being confused about a piece of code that's breaking production, and finding the author made absolutely no effort to communicate what the change was and why it was made: no commit message, no PR description, no detail on the ticket, no code comments, no documentation, and they left the company last month – great, I guess I'll spend the rest of my day figuring that out then. Better hope this is happening at 10am and not 10pm.

My hope with my own work is that, if I'm away, and even if it's a few years on, other engineers on the team will have an easily-accessible window into some of my rationale and thought process: what I was trying to do, why I was trying to do it, risks I knew about, anything I thought was non-obvious at the time. My reasons might hold up, they might not – what's important is that other engineers can see what I was thinking.

This is especially important if the team has low confidence when making code changes: maybe the relevant experts have left, or there's legacy sections of the codebase that haven't been changed for a few years, or test coverage isn't good enough to provide certainty when refactoring code, or there's an ongoing incident and everyone is anxious about pushing the right fix. Again, the benefit is being able to make better decisions – quicker and with more confidence – because you have immediate access to information that improves your understanding of the situation.

This is another personal benefit. If I run git log --author=duck, I see a clear chronological list of all the code changes I've made on a project, with much higher fidelity than I could possibly provide if I had only written a one-line subject.

I find this a useful tool for understanding what I've actually done this quarter, or year, or even in my time at a company^[3]. Whenever I've left a job, I've always checked the git logs shortly before leaving, and each time I've found changes that I had forgotten about but that were valuable contributions or interesting technical items, suitable for pulling into future interview conversations, or to include in my CV.

I'll often run git log to see what changes have happened in a project recently. Usually I come away with limited information – I can see who is committing to a repo and some of the keywords in the commit subject lines. But when those messages contain just a few sentences on what the change is and why it's being made, then I build up better awareness of what's being done and I learn more from my co-workers. Particularly in a remote-heavy environment, you have to be explicit about building that kind of awareness in a team by repeating the information and making it easy to find, and the git log is an ideal place to do that because people will see it naturally.

This kind of knowledge-sharing benefit also applies to historic commits: the git log can be a great learning resource when somebody new joins the team, as long as it contains appropriate detail.

The act of writing a commit message forces me to think about the work: if I can't write a concise explanation of what I'm doing and why, then maybe I shouldn't be doing it, or maybe I need to be breaking the work into smaller logical changes. Or, like rubber duck debugging, I might realise something new about my implementation when I try to explain it. Or maybe I can't articulate a message because I don't understand the technical or product details well enough, and I need to take a step back and do some learning. By doing this in the commit message, it forces me to confront it early and explicitly.

Some of the value I've mentioned applies to the practice of writing PR messages more generally on a git forge service like Github or Gitlab. And, those services do have benefits that aren't easily replicated in the git log – eg. videos and images, or comment threads.

But the big advantage git has is that, if you're using it, it's at your fingertips through the whole process of writing software. I will probably check the git log after I've run pull. I'll certainly check it as part of any rebasing or merging work. If I'm curious about a line of code, I'll run git blame and look at the commit that introduced it. It's there throughout the development process, and there's value in having that extra information right in front of you in the tool you use every day, in a way that's seamless to access.

I don't think having a merge commit that links to a PR or a ticket is an adequate replacement. Maybe as a one-off, the few extra seconds clicking through the link aren't a problem, but for something that I do many times per day it adds a lot of friction. If I'm debugging a production issue and I have five commits that I'm interested in, and they all just link out to other PRs, and then some of those PRs just link through to other tickets, it significantly reduces how quickly I can understand details about the codebase and its changes, and increases the cognitive load at the exact time that I need things to be quick and easy to understand so I can debug an urgent problem.

Another place where git has an advantage is searching: yes, I can go to Github, search for a term, queue up browser tabs for all the found PRs, and look through each of them individually to find what I want. But searching the git log in my terminal is absolutely trivial and instant: I type git log, it opens less or another pager, I hit forward slash, I type my search term, and I can page through the entire history of the repo interactively in a few seconds. Or I can run it through grep, or narrow it by directory or a particular set of files. The experience isn't comparable – it's literally 10x faster to find what I want using git, the data is all local so I can do it offline, and we don't need any special tools other than git itself.

That's fair – if it's very urgent then link to a ticket or postmortem doc that can be updated later. If you can spare a few minutes though, keep in mind that production incidents are a time when clear, explicit reasoning and communication around the code change are particularly important.

That's a pretty good reason. If my diff contains useful comments or docstrings I'll sometimes just mention that in the commit message. You can also copy useful info from the code comments into the commit message, the duplication isn't a problem.

For more junior engineers, I think this is understandable. The times where I've really not wanted to explain myself are times where I've not entirely understood what I'm doing or why I've been asked to make a particular change. If I just don't leave a message, then I avoid the risk of getting it wrong and looking silly, I don't have to admit to anyone that I don't understand, and I won't have my ignorance encoded in writing forever. It's easier to not do it.

This is just something you have to overcome: the career involves a lot of not knowing things and having to learn them, it's normal. For me it's become easier over time to share when I don't know something, because I'm more secure that there are things that I do know, and I've had times where I've seen the payoff in those old messages – the value has outweighed the embarassment.

This is the reason I've heard the most – people think it's valuable to leave some contextual information somewhere, but prefer to do it on the PR or in an issue tracker.

The git log certainly has limitations. It's not a place for video or images, it doesn't contain your review comment threads, it's not very accessible for Product or other orgs, and it only captures state at the point in time that you made the code change. By using a tool that's decoupled from the commit, you can use richer media or access information that wasn't available when the commit was made – eg. maybe you can see deployments in your git forge tool or alongside a ticket. That information can be extremely valuable for understanding the particular code change and its impact, and so there are more suitable places to put this contextual information than the git commit.

To this I'd argue: if your tooling is consistent through the team, it works and it puts all that information in front of you instantly in the same way that running "git log" does, then that's excellent and it's a workflow to aspire to.

But, just because PRs and other tools can hold similar information, it doesn't make the git log useless. If you're using git to commit changes, then people will very likely want to look at the log at some point, and it doesn't hurt to duplicate some information so that the commits can be read more easily.

As mentioned above, I think git puts the information in front of you in a more naturally accessible way than forge tools – I don't find PRs an adequate replacement. But even if you prefer the UX of web-based tools, there's another argument for git: open-source version control tools are likely to outlive the data in SaaS services. This is admittedly low down on the list of problems for startups, but people do make repos private, they do misconfigure Jira and lose state, git forge companies accidentally delete production databases, license or pricing changes can force you out of a service, servers go down, accounts get closed, companies go out of business, and sometimes you just decide to change to another provider – shit happens and that data can go away, or the ties between the data and the commit can be broken. Meanwhile every engineer in the team has their own immutable offline copy of the git history, where the commit messages will persist for as long as the code does.

Some personal git workflows make it harder to write messages. If that's the case for you, then that probably means the workflow also makes it hard to make and merge useful logical commits, and I'd argue that you should consider changing it^[4].

Some team workflows also make it harder to write messages, and if you can't influence the team to change conventions this one can be awkward to work around. For example, if your team's tooling is forcing a squash of your commits when the PR is merged, this will replace your deliberate commits. If that's the case, hopefully you can disable that feature on a per-PR basis – if not one thing you can do is include a clear message in the merge commit description.

Face to face communication can be higher-signal, and some things can be better communicated verbally, but unless you're recording the call and providing a transcript or notes, it's all lost the moment the call ends, and it's not accessible beyond the participants of that one meeting. If I come across the commit in six months time, I won't remember the full content of that discussion, and I might not even remember that we had a meeting about this change. Writing is more permanent and increases in value over time as people forget. At the very least, record the video or audio and link to it.

If you don't want to spend 10 minutes extra writing a message for a logical code change, I think you should reconsider as the ROI for the team is significantly higher than that investment^[5]. If you really struggle and it takes hours then this could be a valid reason. If you have a way to share screencasts with your team, that can be an alternative solution.

If you already write notes on your PRs, then there's almost no extra cost at all, as you're already spending time writing about the change.

Useful commit messages will highlight context that can't be reliably inferred from just reading through the diff – that's the value of them. Certainly it's possible to write bad messages, but I don't think the potential existence of bad messages should prevent you from trying to write a good one.

I want that too sometimes – there are various ways to achieve it, including the git log --oneline flag.

I do appreciate that not everyone will want to read messages or find them useful, but I've seen it help myself and other engineers in the past, and I've seen the cost and frustration when key context about a change hasn't been made easily available. Even if you personally never want to read the messages, there's no big cost to adding them: you're not making a tradeoff where you're losing something by including extra information in your commit message, and they're easier to write than code comments because you don't have to worry about how they'll change in the future – you just have to capture what you're thinking now. The only thing you'll lose is a small amount of time invested in writing and sometimes editing the messages.