The what and why of git commits


Git commits can have multiple commit messages attached. I find them most useful like this (but hey, you do you):

  • the first message is short, and says what I am changing
  • the second is usually longer, and details why I am changing it.
git commit -m "Change thing" -m "Long context
  for why the thing needs changing. You can
  write a whole essay here, if necessary."

When using a text editor to write the commit message rather than doing so inline, the messages can be separated by inserting an empty line, so that the message looks like this:

Change thing

Long context for why the thing needs changing.
You can write a whole essay here, if necessary.

# generated content goes below:
# Please enter the commit message for your changes. Lines ...

Why bother? Well, I treat commit messages as a kind of dev log to myself. I sometimes include suggested next steps in the longer message. Then, when I come back to the project (usually later than intended 😬), I can read about what I was up to, and get some context back. Git hosts like GitHub, GitLab and BitBucket know what to do with these multiple messages, and can show more or less detail depending on the page. In the top level repository view, only the first, short, summary message will be shown next to files. In other views of commits, the whole message is available.

I find including a longer “why” message very helpful for keeping a record of debugging. Especially so if I’ve been fixing a weird bug, or something at the edge of my understanding. If I change something and it reintroduces a bug, I can look back at the commit in which that thing was last changed, and read a little message about why it is the way it is. Here’s an example, a commit from this very site. I didn’t write it for this post, this is how I write to myself.

Fix 404 on non-home pages
Okay, this is a doozie. Ultimately, the change needed was to set
`trailingSlash="always"` in `svelte.config.js` (and consequently
change image urls).
We had the trailing slash problem, see
[Trailing Slash Guide](
The routes that were generated for posts ended in `[slug].html`
(eg, `tldr.html`), instead of `/[slug]/index.html`. Different
webservers treat this differently. Turns out Vercel's webserver
didn't like the direct `[slug].html` form.
As a consequence, when a visitor would visit any page except the
homepage _directly_ (which has an index.html), a 404 would be
served (and not the custom 404). When linked from
the homepage, the page would appear fine, no 404. That's because
SvelteKit was changing the route and mounting new page content,
because the route is dynamic (based on the md pages). I have a
flimsy and tenuous understanding of this.
By using the `trailingSlash="always"` configuration, we always
generate an index.html for a route. However, that changes the
relative directory for images (it adds one more directory, so
image paths could have been changed to
`'../../images/image.png'`, adding a `'..'`). Instead, I've
imported the `asset` path from SvelteKit's built in `$app`
module, and made image paths relative to that, using an explicit
`<img/>` tag.
Hopefully no more 404s! (Also hopefully true static site now:
I think it may have still been rendering via SSR when linked
from homepage.)
A relevant issue:

Kind of a long message for a single line change to config! (Alright, alright, there were six additional files touched to change the image tags as described, but the logical change was enabling one option in a config file). It definitely warranted that little essay though: I have since revisited it when I changed the site, and been glad I put my thoughts down at the time.

Thanks for reading. If you'd like words like these in your inbox, sign up below. Or just check this site occasionally. Or run, now, and never speak of this place. You do you.