A busy week for me, so a short post on my thinking around using Git for writing.

Writing

Even when using paper, I’ve long tried to record the history of what I write as I write. Perhaps I’m a hoarder of sorts. However, I do believe such hoarding of details is conducive to reflective thinking, which can then be used to improve one’s skills in any area… Perhaps I’ll write more on reflective thinking later.

Since I started using Git for code, I have often wondered about its potential for writing and in enabling a more reflective approach to the craft.

Problems

While Git works beautifully for code, when one starts to use it to track one’s writing, problems immediately become apparent. For a start, changes in Git tend to be tracked on a line-by-line basis; when writing it’s much more common to add, substitute, move or remove words. Furthermore, a line in code often constitutes what we’d call a paragraph in written prose. It is possible to see changes on a word-by-word basis in Git (git diff --word-diff=porcelain in the command line, for example), but this isn’t so easily doable when patching files as I often do to break a long session of work into a series of commits.

These details aside, I’ve been focussing on a higher level of using Git for now – namely, what would be an appropriate workflow for writing.

Specific Context

Whilst I want to use Git for all sorts of writing – reviews, essays, even poetry and fiction – it made sense to try and come up with a model for writing my (this) blog first. I wanted a way to track any ideas I might have for posts, a way to draft them and record changes I made as I went, to track the editing process, and finally to publish.

Solution

The model I have for my blogging now sounds quite simple but I’ve put some consideration into it.

I have a drafts folder which contains a folder for each and any post I happen to be working on (there are currently quite a few). Each folder contains a README.md file which is the post itself in Markdown format, and a metascrp.txt file containing information about that post, as explained earlier on this blog. Also mentioned earlier is the script I have written pushing posts out to Scriptogram which combines these two files.

I now also have an archives folder which I move any folder/repository in drafts to when it’s published. This gets it out of the way and means I can focus on what needs doing next, without a lot of clutter. It also means I still have all the history of writing and editing.

Here is the creation of a post in series of steps:

  1. Have an idea for a blog post.
  2. Create a folder in drafts for the idea.
  3. Initiate a Git repository inside.
  4. Create a README.md inside the new folder and track with Git.
  5. Start writing and commiting.
  6. When a first draft of sorts is complete, create a new file called metascrp.txt and track with Git.
  7. Add to metascrp.txt any attributes regarding the post for Scriptogram (title and date as a minimum).
  8. Redraft and edit README.md (the post) as necessary, continuing to add and commit.
  9. When ready, run script to push the post and its attributes to Scriptogram.
  10. Now published, move the whole folder from drafts to archives.

For step 1, I am currently using a spreadsheet to track ideas I have and what stage they are at in the writing process.

I’ve put my script and folders (empty of content) into a GitHub repository, along with a bunch of README files to help clarify the process for anyone else who might want to adopt it.

What next?

A lot of this is still manual. It shouldn’t be too hard to write a few shell scripts that handle the movement automatically so that’s likely what I’ll do next. Separately, I want to look at handling ideas within the same folder and model rather than relying on external spreadsheet tool.

I’ll continue to add to the GitHub repository and post updates here.