Flashbake: free version-control for writers using git.

For the past couple weeks, I've been working with Thomas "cmdln" Gideon (host of the fabulously nerdy Command Line podcast) on a free software project for writers called "Flashbake" (which is to say, I described what I wanted and Thomas wrote the code).

This is a set of Python scripts that check your hot files for changes every 15 minutes, and checks in any changed files to a local git repository. Git is a free "source control" program used by programmers to track changes to source-code, but it works equally well on any text file. If you write in a text-editor like I do, then Flashbake can keep track of your changes for you as you go.

I was prompted to do this after discussions with several digital archivists who complained that, prior to the computerized era, writers produced a series complete drafts on the way to publications, complete with erasures, annotations, and so on. These are archival gold, since they illuminate the creative process in a way that often reveals the hidden stories behind the books we care about. By contrast, many writers produce only a single (or a few) digital files that are modified right up to publication time, without any real systematic records of the interim states between the first bit of composition and the final draft.

Enter Flashbake. Every 15 minutes, Flashbake looks at any files that you ask it to check (I have it looking at all my fiction-in-progress, my todo list, my file of useful bits of information, and the completed electronic versions of my recent books), and records any changes made since the last check, annotating them with the current timezone on the system-clock, the weather in that timezone as fetched from Google, and the last three headlines with your by-line under them in your blog's RSS feed (I've been characterizing this as "Where am I, what's it like there, and what am I thinking about?"). It also records your computer's uptime. For a future version, I think it'd be fun to have the most recent three songs played by your music player.

The effect of this is to thoroughly -- exhaustively -- annotate the entire creative process, almost down to the keystroke level. Want to know what day you wrote a particular passage? Flashbake can tell you. Want to know what passage you wrote on a given day? That too. Plus, keeping track of my todo.txt file means that I get a searchable database of all the todo items I've ever used, with timestamps for their appearance and erasure.

Additionally, since git repositories are made to replicate, you can publish some or all of your projects to the public web or to a private site. I'm hoping that my publisher will use a public git repo to check out the most recent versions of my in-print books every time they go back to press for a new edition, and use the built-in compare ("diff") function to find all the typos I've fixed since the last edition.

It's all pretty nerdy, I admit. But if you're running some kind of Unix variant (I use Ubuntu Intrepid Ibex, but this'd probably do fine on a Mac with OS X, too) and you want to give it a whirl, Thomas has made all the scripts available as free software. He's working on a new version now with plugin support, which is exciting!

I love adapting programmers' tools for my writing. They tend to be extremely well-made and stable (because if they aren't, programmers will fix them or find better ones) -- it's like using chefs' knives in the kitchen.

Install.

Flashbake's installation and configuration documentation is already pretty complete, so I won't duplicate it here. In short, to run Flashbake, you'll need superuser access and the following installed as usual:

• Python with the setuptools module
• Git

Once you've laid that groundwork, download the latest version of Flashbake and extract it. In the extracted directory, run:

sudo python setup.py install

Now you're ready to start your project. Create a new folder—I called mine write—and cd into it. Then run:

git init

Make the first text file you're going to track with Flashbake, like my_novel.txt, and type a few lines. Now you're ready to start tracking its revisions with Flashbake. Create a new file in your project directory called .flashbake (don't forget the starting dot) and add the name of your text file to it. For example, my Flashbake project tracks two files, called my_novel.txt and this post in a file called flashbake_automates_version_control.txt. So the bottom of my .flashbake configuration file looks like this:

# "Hot files" for flashbake to commit, add yours here
my_novel.txt
flashbake_automates_version_control.txt

(Flashbake ignores the first line, which starts with the #, because it's a comment.)
Now we're almost ready to run Flashbake. First we've got to configure a plug-in or two.

Shake and Flashbake Plug-ins.

Flashbake plug-ins are the secret sauce that make it a worthy interface to Git. Plug-ins automatically add information to each version's commit notes, like feed items, the weather, and timezone.
Here's a full list of the default plug-ins that come with Flashbake. I used four plug-ins in my Flashbake project: weather, timezone, Twitter, and the feed plug-in. As the Flashbake plug-in documentation explains, list the plug-ins you want to use in your .flashbake file and its additional parameters below.


 Publish Your Flashbake Git Repository to GitHub.

Now you've got a local Git repository of file versions. Great, right? Well, not if you can use 'em easily. Git newbs don't know all the commands to search and diff between versions, but luckily a pretty web hosting solution for Git means you don't have to know the commands. I published my local Git repository to GitHub to show off my file changes in this post. Register for a free account at GitHub and create a new repository there. Then, push your local repository to GitHub for cloud backup and a good-looking web interface to your project. Use GitHub's setup instructions to do just that. After I created a repository on GitHub called write, GitHub told me to run the following commands (where "existing_git_repo" is your project directory):

The git push origin master command is the magical command that pushes your local files to GitHub. By default, you have to do that remote push by hand, but if you're automating Flashbake's runs, you can make local commits automatically push to a remote host (like GitHub) using this handy command.
Flashbake is still a very young mechanism for driving Git, and more plug-ins and configuration options are becoming available, so we've only scratched the surface here. But adopting programmer version control for writing, lists, or notes is something more and more tech-savvy folks will do going forward. Thanks to Leo Laporte and Cory Doctorow for making me aware of Flashbake in this episode of This Week in Tech.

Custom Search

If you liked this article, subscribe to the feed by clicking the image below to keep informed about new contents of the blog: