[stinos]

Sort of an interesting idea, and I wholehartedly agree with

ensuring that each and every commit serves a singular purpose and adds to the narrative history of the project has done wonders to reduce thrash and the introduction of “stupid mistakes”.

Read in chronological order, these commits should paint a clear picture of how and why this particular code came into existence and how it has changed over the course of its life.

I'm not sure if this is particular to 'literate', to me it sounds more like common sense, but yes: that is how I like commit history.

The example https://github.com/pcorey/delete-occurrences-of-an-element-i..., even though the OP mentions it's a toy, illustrates this pretty well. Without knowing much about the code you can just read the commit messages and even though the style of the text is a bit too fuzzy for my liking at times (i.e. lots of words just to form nice prhases to make points which could be made with shorter and more to-the point sentences) there is a much larger problem (imo): the first line of each commit makes no sense whatsoever wrt what actually changed in the code. This makes it impossible to at first sight (in git user interfaces which use the first line in their commit lists, i.e. the vast majority I think) find out what is happening and what a particular commit does. If that is an articfact of literate commits, then sorry but that is just not very good. Here's an excerpt:

    # Getting Real
    # Forging Ahead
    # Keep it Simple
    # Our First Test
    # Take What We're Given
    # Laying the Groundwork

Suppose you come back to this knowing you changed something in a recent commit and want to look it up. My strategy is then usually to just glance over the history for a few seconds to see if I can immediately find the commit I'm looking for before starting an actual search. Works very, very often. Not so much in this case. Compared to what I'm looking at right now in a repository of a team I work with:

    converters: Fix nullable double getting converted into NaN
    plot: Use assembly reference instead of project reference
    plot: Update code style and formatting
    network: Add functions for element acces to Python scripting API

The body of the commit message then goes on describing more detail and usually also why the change was made. As such creating the narrative the OP talks about. But with the added benefit that the message header provides pretty good insight into what a commit does, hereby providing some kind of index to the book being written, making it much easier to discover things.

[pcorey]

Yeah, I agree that the subject of those commits are far from helpful or descriptive. To be honest, they were written as cheeky subheaders for the generated example article, and don't even do a job there.