Git for authors

15 thoughts
last posted April 20, 2016, 3:33 p.m.
get stream as: markdown or atom

Git is a tool for version control. It's mostly used for software source code. Some people think it's a good platform for writers as well. I don't think so.


It's my contention that while Git solves a number of issues that arise when managing code, it offers no unique solutions for writers and editors, and introduces a lot of needless complexity in the process.


Aside: Comments by git inventor Linus Torvalds raise doubts in my mind about the optimalness of git even for its intended use case (source code):

You released the Git distributed version control system less than ten years ago. Git caught on quickly and seems to be the dominant source code control system, or at least the one people argue about most on Reddit and Hacker News.

Git has taken over where Linux left off separating the geeks into know-nothings and know-it-alls. I didn’t really expect anyone to use it because it’s so hard to use, but that turns out to be its big appeal. No technology can ever be too arcane or complicated for the black t-shirt crowd.

I thought Subversion was hard to understand. I haven’t wrapped my head around Git yet.

You’ll spend a lot of time trying to get your head around it, and being ridiculed by the experts on github and elsewhere. I’ve learned that no toolchain can be too complicated because the drive for prestige and job security is too strong. Eventually you’ll discover the Easter egg in Git: all meaningful operations can be expressed in terms of the rebase command. Once you figure that out it all makes sense. I thought the joke would be obvious: rebase, freebase, as in what was Linus smoking? But programmers are an earnest and humorless crowd and the gag was largely lost on them.

Linus Torvalds goes off on Linux and Git, Sep 25, 2012


What does a typical writing/editing workflow look like? Say we're talking about a novel, or a blog post.

  • There's almost always a single author.
  • Draft 1 → Draft 2 → … Draft npublish

Perhaps an editor or proofreader gets involved. They end up bouncing drafts off each other.


They're both text so any tool that manages text workflows could be used for both; but source code and prose have great differences in practice:

Source CodeProse

Source code often has multiple authors.

Prose works have usually only one author and perhaps an editor.

Source code is functionally sensitive to tiny changes and portions are closely interdependent. Even small edits can have great effects on usability, or even mean the difference between a working and a broken product.

Prose is not functionally sensitive even to large-scale changes (it's not going to become somehow unusable if you mix your metaphors or misspell a word).

Source code is frequently reused and extended in whole or in large parts.

Prose loses value when directly reused since it derives most of its value from its originality.


You can see how a tool designed to handle the challenges in the left columns is going to be inherently complex.


Do you need to be able to do this with your novel or your blog post?


Most people understand this to be ridiculous. But let's get back to the possibilities tech-savvy writers are actually proposing/attracted to.


Git is built for complex use cases, but perhaps it works just as well for simple ones?

Maybe it can be skinned or otherwise humanized for prose authors?

and my personal favourite (not even being sarcastic)

Maybe git could help authors passively capture valuable revision history that often slips through our fingers and is lost?


Another example exchange regarding that last one:

@brennen @ayjay I can’t think of a thing authors need that they can’t get from File: Save As

— Joel Alexander Dueck (@joeld) March 19, 2014

@joeld indeed, we already have "undo" for that. Having a detailed history of the creation of a text is, for me, another question altogether.

— brennen (@brennen) March 19, 2014

(emphasis added)


Mandy Brown just redesigned her epic personal site A Working Library. In her redesign notes she mentions git:

Now instead of a database I have a folder full of Markdown files, and I can fire up any old text editor to work on them. I can’t recommend Jekyll for everyone—it requires a comfort level with GitHub and the command line that I wouldn’t impose on many writers—but it made perfect sense for me.

I find a comment like this very valuable coming from Mandy — not least because she founded Editorially, which (as I will argue later) provided nearly all the collaboration and versioning functionality that a lot of writers are trying to approximate with git, and did a vastly better job at it.

Here's what I infer from this (though I could be wrong): Mandy doesn’t think imposing git as part of a collaboration or publishing workflow is a very good idea for most writers.

Curious: does she use git simply as a hit-publish mechanism, or is she finding value in git’s core features like versioning and branching? Has she ever tried using git for collaboration on works of prose?


Another example of Git's inherent complexity: Git Flight Rules. In the intro, she quotes Chris Hadfield from An Astronaut's Guide To Life:

Flight Rules are the hard-earned body of knowledge recorded in manuals that list, step-by-step, what to do if X occurs, and why. Essentially, they are extremely detailed, scenario-specific standard operating procedures.

This is an astronaut talking about a type of documentation useful in flying the space shuttle. Kate's premise is that we need something similar -- a collection of detailed, non-obvious solutions for weird but not-unusual problems painstakingly collected through hard experience -- for Git. This popped up on Pinboard's "Popular" page today, which attests to the fact that lots of git users see value in this.

My takeaway is that Git imposes a degree of mental overhead which at least approaches that experienced by astronauts operating a space shuttle. I'm not saying it's impossible to understand or that it's not worth understanding; but that this amount of mental overhead is overkill for the comparatively simple needs of prose writers.


Paul Ford is writing his book with git, because he is Paul Ford.