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!

Dead Rich (2006)

Part of the prize for winning the Nokia Shorts Competition with HAVE I PASSED? was a small budget to make another short film. Tom Wright and I came up with the idea to do a single camera shot out of the coffin at an open casket viewing before a funeral. It took us fourteen drafts to write in all the plot-twists and create a very British farce, and the icing on the cake was securing our amazing cast including Alison Steadman, Anna Wing and David Horovitch. And so in November of 2005 we rehearsed the script on a Friday, assembled the set on a Saturday and shot the film on a Sunday. The film premiered at the Palm Springs International Short Film Festival in August 2006 where we got a great shout out from the Program Director Anita Monga who called DEAD RICH “hilarious” in all the press. DEAD RICH also played at the 14th Raindance Film Festival and picked up distribution through Shorts International.

Have I Passed? (2004)

Here’s an old short we made for the Nokia Shorts Competition back in 2004.  It was my first project with Maya and Shake which even included a rudimentary HDR probe.  The brief was to make a 15-second film for mobile phones on which the public would vote to choose the winning entry from a short-list of finalists.  HAVE I PASSED? ended up winning the competition and (spoiler alert, watch the film before clicking through) even got a mention on the BBC website.  The film screened at the Raindance Film Festival and eventually on the BBC and UKTV.

Depth and breadth of shot folders

Infinity... by shioshvili, on Flickr
This photo, “Infinity…” is copyright (c) 2002 shioshvili and made available under a Attribution-ShareAlike 2.0 license

A brief digression on the topic of folder hierarchies for VFX sequences, shots and the like.  Obviously many shows and studios use some form of ‘[path_to]/show/sequence/shot’ but I’ve always wondered if there was any good criteria for establishing the shot folder structure.  One such criteria is implicit and is of course the structure itself, which is to say, a fixed set of rules that is common to some unit like a shot folder; see also file naming conventions, of which a good discussion can be found here:

I’d like to think another criteria is readability.  For example sequences usually, though not always, have names.  Indeed, you might be surprised to learn that there have been animated features where sequences were purely numerical.  Doesn’t sound too bad except that there is or was no guarantee that sequences appeared in the final film in numerical order.  This often led to ‘that scene’ in which ‘that thing’ happened, and many trips to those production oracles who had internalised the numbers and effectively become human search engines.

Giving sequences names like ‘ET Goes Home’ instead leads to an abbreviation (etgh) and names for the shots associated with the sequence (etgh010, etgh020, etc.).  This is something the author of the article above does too: use abbreviations that help with readability, including an established schema for 3D passes and user names (amongst others) in file names.  So certainly readability seems to be a criteria in good file / folder naming conventions.

Ah but if only it were that simple.  The depths to which some searches lead for sub-folders nested at infinity is nothing short of epic.  There is so much to choose from: departments, software packages, artist names, workflow steps, render passes, tests and on and on, clearly temptation is rife.

I was delighted therefore to find a paper titled “The effect of folder structure on personal file navigation” (which you can download from the publications link here:  In it the authors investigated the relation between users’ folder structure and personal file navigation, looking at the retrieval time and success rate of participants of the study.  The three parameters under consideration were folder depth, size and breadth (number of subfolders); and of course there was going to be some sort of trade off between large shallow folders and small deep folders.

The researchers found that each additional folder step increased retrieval time by 2.236 seconds, whereas for an additional file in a folder it was 0.106 seconds.  Divide the two and you get a ratio of 21, or what they coined the up to 21 heuristic.  That is, each folder deeper equals about 21 files in terms of retrieval time.  What is interesting however was that they found the mean folder size of their participants to be 22 files with 67.3% of all folders containing up to 21 files.  In other words, people arrange their folders and sub-folders this way intuitively: most folders will have about 21 items in them, at which point sub-folders take over.

The 21 rule makes for another good criteria in deciding on folder structures.  For example, we might avoid using a 2D and 3D folder, and place all application folders at the same level.  We can also feel comfortable having 21 non-folder items at the shot level if they are common to all shots.  For example, if all shots feature a reference clip this need not live in its own folder called ‘ref’ since doing so increases retrieval time unnecessarily.

For the VFX project at hand, then, I will be using a shot folder structure in which as many folders sit at the top level within the shot folder (21 rule) as is possible (readability, structure).  In particular, this is the current shot folder structure:

  • after_effects: after effects scripts
  • plates: original frames (or movies) with handles
  • mattes: e.g. matte generated from mocha for use in nuke
  • maya: maya project folder
  • nuke: nuke comp and precomp scripts
  • paintings: matte paintings
  • photoshop: photoshop files
  • reference: any reference material for the shot
  • renders_3d: 3d passes
  • renders_comp: rendered shots for approval and nothing else

A Sci-Fi Comedy

John lies on the ground (Signal Failure)A couple of years ago we decided to make a low-budget indie feature using whatever resources available to us.  Our philosophy was to ‘quit planning and start doing’, which happened to be one of the themes of the film.  Over the next few years we shot scenes whenever we were all available (and in the same country), exploiting our digital format as much as possible: lots of coverage, move quickly and keep a lean crew.

The result is SIGNAL FAILURE, a 110-min sci-fi comedy about the desperate attempts of an ‘almost-30’ year old inventor to make his mark on a world in which security cameras follow his every move and thwart him from fulfilling his potential.

It is said that making a feature is a marathon and not a sprint, and SIGNAL FAILURE has been no exception.  The hours that have been poured into the project by everyone who’s worked on the film, all of whom volunteers, has been nothing short of staggering.  And there is plenty more to do.

As we begin working on the visual effects — and there are a considerable number of shots — I thought it interesting to document some of the work required to get the shots out the door.  I’ll try and share some of the problems we encounter and solutions we come up with, as well as what tools we use and what we build ourselves.

Our starting place is Final Cut Pro 7.0.3 in which we have 9 reels of approximately 12mins each.  Our aim is to create a Dropbox type folder containing shots that artists can work on irrespective of their location.  Our compositing tool of choice will be Nuke v6.3 or later, so each shot folder should at least have a ‘nuke’ and ‘render_comp’ directory.

The film also includes a variety of effect that will have to be accomplished using either Houdini or Maya, but more on that as-and-when.

For now I’ll also just mention that our plan is to work through the film reel by reel so that everyone involved can get a sense of the overall progress.  Fortunately there are a lot of ‘same-as’ shots so that things should pick up as we move from each reel to the next.