Atom, Fountain and Git-Flow

Benjamin Zephaniah's Typewriter
Benjamin Zephaniah’s Typewriter (UK, 12 September 2012)

Comment: this blog post is quite top-level, skipping over many details. However all the pieces mentioned are widely documented. Don’t be put off by the technical component, however: the approach is well worth the effort, in my opinion.

When I was writing my thesis using LaTeX, a markup language used to create scientific and mathematical documents, it occurred to me that something similar would be very useful in writing screenplays. You would write your screenplay in a simple text editor using in-line commands for character names, scene headings, dialogue and so forth, and then turn the text into a properly formatted screenplay using a parser.

Years later it turns out many folks had similar ideas which have coalesced into a screenplay markup language called Fountain. Plenty of apps that parse, display and convert Fountain markup (and more) are listed on the official site too.

However one great little text editor that isn’t mentioned is Atom, which is developed by GitHub. What makes Atom particularly good is its ‘hackability’ and library of plugins already available. In particular, user Superlou has added Fountain Support for Atom which you can install directly through Atom > Settings > Packages (search for Fountain). As detailed on the GitHub page for the package, it comes with the following features:

  • A scene list navigator (CTLR + ALT + o)
  • Formatted preview (CTRL + ALT + M); note the capital ‘m’
  • Symbol listing (CTRL + r); via symbols-view package

Well why stop there? Atom was created by GitHub and has built in support for Git, a version control system which allows you create a history of your drafts as you evolve your story.

There are plenty of introductions to Git, for example this one. However, most of the functionality is available through the git-plus package for Atom. Once installed, you can make commits, push and pull (and more) through the Atom > Packages > Git Plus menu.

Though you can sign up to GitHub and create private projects there, it’s is cheaper and just as straightforward to do this locally. The idea is to create a folder on your favourite cloud storage folder (Google Drive, Dropbox, other) for all your writing, below which you create a bare Git repository per project. If your top folder is called ‘writing’ you would create a bare repository for your project using a command like:

git init –bare writing/casablanca

Once you have your bare repository, which is then synced across your devices, you would clone the repository to a working directory in your default documents folder. The easiest way to do this would be to get familiar with SourceTree, or something similar. Using SourceTree you could SourceTree > File > New / Clone and make a clone of your local repository into your working documents folder; so you would be creating a repository and working copy per screenplay.

You are then able to add .fountain files to your repository using standard Git practise (i.e. add and commit) and sync your work to other devices using push / pull; you can use a combination of SourceTree GUI or Atom menus to run these commands.

Having used this system for some time now I definitely recommend working this way, assuming you’re up for the technical challenge of setting it up.

Lastly you can take it one step further still, by adopting Git-Flow. Git-Flow is a way of working with Git, in particular branching, to enable successful collaboration in software development. Of course, where you read ‘software development’ you can also read ‘screenwriting collaboration’, even if that collaboration is with yourself.

For example, in GitFlow you adopt several branches:

  • Master: for the code that is live, with tags representing versions
  • Develop: for the code that is being worked on, which everyone feeds into
  • Release branch: take what’s in Develop, prepare it for release and then merge it into Master along with creating a new version tag (delete this branch once done)
  • Hotfix branch: take what’s in Master, fix what’s broken and then merge it into Master along with creating a new version tag (delete this branch once done); also merge the fix into Develop
  • Feature branches: take what’s in Develop, add a feature and merge back into Develop (delete this branch once done)

Note that you can ditch a feature branch with no consequence.

Here’s how I’ve been using this model with screenwriting:

  • Master: the latest complete draft, with tags representing versions
  • Develop: my current rewrite, represents a complete screenplay (unless first draft)
  • Release branch: take my current draft, create a PDF and merge the draft into Master to update my latest complete draft (Fountain text file) with a PDF
  • Hotfix branch: I’ve found a typo or mistake, fix it and delete the branch once done (requires regenerating the PDF too)
  • Feature branches: a rewrite of e.g. a scene or act; an experiment; may have several of these on the go

Happy writing!

Leave a Reply

Your email address will not be published. Required fields are marked *

%d bloggers like this: