What is Permanent Marker?

In my last post, I hinted I’ve started a new project that I’m calling Permanent Marker. What’s it all about?

The main idea of Permanent Marker is to bring git from the world of writing code to the world of writing English. As programmers, we rely on git for version control. This is important for writing English, too! The most terrifying thing that can happen when writing is losing your work. Permanent Marker aims to be a writing environment where this fear doesn’t exist: It uses git under the covers to maintain a version history of all of your writing.

The main data structure for Permanent Marker is “a bunch of Markdown files in a git repository.” There isn’t anything particularly innovative about that. For years, tools like VSCode (for programming) and Ulysses (for English) have provided excellent experiences working with collections of files in a directory hierarchy. What I’m exploring with Permanent Marker is how to integrate git into the writing workflow, as opposed to the programming workflow.

Here are the main ideas I’m playing with for bringing git to writing:

  • All writing starts in an unpublished state. I represent this as a “scratch” branch created in the git repository holding the content.
  • As you edit a file, it’s automatically saved every 5 seconds and committed to the scratch branch. To prevent an explosion of tiny commits, I will amend the previous commit in the repository if it’s to the same file and the commit isn’t “too old”. The goal is that an author, without thinking, will be able to keep distinct versions every N minutes of every file she works on.
  • When a file is sufficiently “done”, you can either publish it (which moves it directly from the scratch branch to the main branch of the repository) or open it for feedback. Whereas all unpublished files live in the same “scratch” branch, I create a different branch for each file in the “feedback” state so reviewers just see the changes to the file that needs feedback.

By far, this work of thinking through how to model writing workflows in git has been the most interesting part of this project. I’ve gained more than an in-depth understanding of git from this project, too. Like any self-respecting developer, I maintain this website as a “collection of markdown files in a git repository” that’s published with a static site generator. Permanent Marker, even in its rough state, helps me edit and maintain this site.