{"slug": "why-i-still-hand-write-my-commit-messages", "title": "Why I still hand write my commit messages", "summary": "Developer Jamie Tanna explains why he continues to hand-write detailed Git commit messages despite the availability of AI tools, citing the importance of documenting the 'why' behind changes, which aids in knowledge retention and ensures understanding. He notes that a 2014 study shows people retain knowledge better when they expect to teach it, and he uses commit messages to take ownership of AI-assisted code and to break down changes into atomic commits with per-commit AI attribution.", "body_md": "For over a decade, I've been a proponent of writing detailed Git commit messages. I find it a valuable use of my time, and continue to double down on it, even in a world where you can get a Large Language Model (LLM) to write it for you.\n\nIn the past, I've [written about at least 89 strong feelings I have about Git commits](https://www.jvt.me/posts/2024/07/12/things-know-commits/), so I'm naturally biased to the benefit of commit messages, but why does this still hold in the current age, where a lot of people are delegating that to an AI agent, if at all?\n\nOne of the most important things a commit message should explain is *why* you're making a given change.\n\nChris Beams' [post about writing commit messages](https://cbea.ms/git-commit/) is probably one of the more cited blog posts of all time, and is a great resource on this and a number of other important pieces to remember when writing a commit message.\n\nUnfortunately a lot of humans, and by extension LLMs, still continue to re-explain what has changed in a given commit. Generally, the \"what\" is clear, as you can see it in the diff itself. Although not all code is \"self-documenting\", you can generally see \"what\" is changed by looking at a commit's diff.\n\nIf you don't document why you're making the change, you're missing out on really important context.\n\nSome other areas I focus on calling out:\n\n`we`\n\n- i.e. `I'd missed this from $sha`\n\nIn each of these cases, it helps provide more insight into what led to the change and why we're doing it.\n\nThe process of writing the commit message is also greatly helpful in determining whether I do actually understand the changes I've just made.\n\nAs we heard [last week at GopherCon UK](https://www.jvt.me/posts/2026/08/14/gophercon-uk-2026/#how-to-stay-passionate-in-the-age-of-ai), [a study in 2014](https://link.springer.com/article/10.3758/s13421-014-0416-z) shows that you are more likely to retain knowledge if you are expected to teach it.\n\nBy making sure that I need to explain why a given commit's changes are necessary, I can make sure I do actually understand what I'm about to commit, and how I'd explain it in my own words.\n\nI'll very often find that - even with changes I've fully authored myself - as I'm going to explain it, I don't necessarily agree with a choice I've made, or now that I've stepped back to review the changes, I can see a better option.\n\nI've found this to be a positive experience when writing documentation in the past, too. When you're trying to explain a new feature, or clarify existing functionality, you often need to \"take a step back\" and rethink how a user who may be unfamiliar with the inner workings of the project will reason about it, and by doing that, you may find that there's a lot of implied understanding you need to break through.\n\nWhen working through my commit messages, I'll watch out for occurrences of `Also, ...`\n\nor `Additionally, ...`\n\n- sometimes they're OK, but it's often a case of a commit that is trying to do too much, which requires breaking down the changes into multiple commits.\n\nIn the case I'm working with some AI-assisted code, I may not have necessarily been the driver of the changes or making a lot of the decisions that were made.\n\nBy having to explain the choices in the commit message, I'm not only working out why the decisions were made, but taking full ownership of the changes.\n\n(regardless of whether you do this or not, if you've committed it, it's your responsibility!)\n\nI work to introduce atomic commits where possible, which allows me to add [per-commit attribution for AI usage](https://www.jvt.me/posts/2026/02/25/llm-attribute/).\n\nIn cases where I am using AI to support a change, I can opt to specify in the commit message exactly what pieces have had AI assistance, allowing a way to call out specific areas the different AI model(s) have been used.\n\nLast week, I'd been working on some personal projects that I've been struggling to make the time to work on, so decided to get my Claude for Open Source (Claude Max) subscription to work.\n\nI decided to vibe it a little, and allow Claude to commit atomically as it needed to. I don't particularly like the way it writes its commits, so I put Claude Fable on the task of taking 100 of my most recent commits and [creating a skill for committing as me](https://gitlab.com/jamietanna/dotfiles-arch/-/commit/eb96ff591ea9fa7bbf66d22bdf3fd38e792ba53c) to improve the resulting commits.\n\nIt wasn't surprising that these commits were better, but not quite my writing style. That's absolutely OK - I don't actually want an AI to be able to write like I do.\n\nBut it is a nice point where in projects I'm not *as* bothered about writing the perfect commit message, I can get something reasonable that sounds a bit more like what I'd want out of it.\n\nIn projects where I do want to write the commits, having a starting point can be useful, too.\n\nI've had an affinity for writing documentation for some time. Some of it is down to my [familiarity with writing as a form of blogumentation](https://www.jvt.me/posts/2017/06/25/blogumentation/), [how it helps my neurodiverse brain](https://www.jvt.me/posts/2023/10/04/blogging-neurodiversity/), but also because I see a tonne of value from better documentation.\n\nI'm definitely not as skilled as a Technical Writer™️, but I've found over the years that between my better writing skills than many of my colleagues, and [have a strong empathy for my users](https://www.jvt.me/posts/2025/04/17/lessons-learned-engprod/#building-empathy), that I'll end up doing more of the documentation-oriented pieces of work.\n\nNaturally, writing commit messages leans into this, as it's another important piece of documentation.\n\nTo be very clear, this is *how I work* and how I want to handle this myself.\n\nEven in the projects I run, I don't enforce this on anyone - I've learned over the years it's not worth it to try and require it - and although I'm happy spending the time doing it, not everyone is as interested.\n\nI find it to be a valuable process, and helps me work through the thinking behind a change.\n\nBut that doesn't mean I'm even \"forcing\" myself to do this - writing can be quite brain intensive, and so sometimes I don't have the capacity to do it.\n\nWant some worked examples?\n\n`upload_time`\n\nof a version", "url": "https://wpnews.pro/news/why-i-still-hand-write-my-commit-messages", "canonical_source": "https://www.jvt.me/posts/2026/08/17/hand-write-commits/?utm_medium=rss&utm_source=rss", "published_at": "2026-08-17 14:51:56+00:00", "updated_at": "2026-08-17 15:42:47.830142+00:00", "lang": "en", "topics": ["developer-tools", "ai-tools"], "entities": ["Jamie Tanna", "Chris Beams", "GopherCon UK", "Claud"], "alternates": {"html": "https://wpnews.pro/news/why-i-still-hand-write-my-commit-messages", "markdown": "https://wpnews.pro/news/why-i-still-hand-write-my-commit-messages.md", "text": "https://wpnews.pro/news/why-i-still-hand-write-my-commit-messages.txt", "jsonld": "https://wpnews.pro/news/why-i-still-hand-write-my-commit-messages.jsonld"}}