Introduction #

Revision is the crux of writing. As writers, we need tools adapted to a complex workflow built on the process of revision. Tools that allow us to track changes, compare different versions, and document the history of a project over time. Tools that do not interfere with the writing process and that help us to delve into deeper flow states, secure in the knowledge that our work will be preserved.

In this quickstart guide, we are going to write a poem and track revisions using a version control system called Git. Version control systems (VCS) are widely used in software development, where tracking changes and documenting the production process is an integrated part of the workflow. Git is a distributed VCS, meaning it is a tool for managing complexity and the revision process in a collaborative, multi-authored setting.

Git has a reputation as a powerful and flexible tool with a steep learning curve. Luckily, the most complex poem in the world is far simpler, on a mechanical level at least, than even the most basic software. So, writers don’t need to use the more advanced Git functions. A handful of fairly straightforward concepts and commands will unlock extensive version control for the dark art of writing poetry. ¹

Get Started #

Tutorials and Tools #

Before we begin, I suggest you check out a tutorial to familiarize yourself with Git. The YouTube series Git and GitHub for Poets is a fun introduction to the subject with lots of detail and engaging exercises. I didn’t work through all of this series, but simply watching the videos for a week while doing the dishes helped me wrap my head around the subject.

How writers can get work done better with Git by Seth Kenlon was the first tutorial on Git that really clicked for me. As a bonus, Kenlon introduces the Atom text editor, writing in plain text, and working with a remote repository in GitLab.

I attribute any success I have in explaining Git to Lorna Mitchell’s Git Workbook. I came across Learn Git in a Month of Lunches late in writing this guide, but it comes highly recommended, and I love Rick Umali’s crisp prose.

Learn Git Branching is an interactive series of exercises to learn how to move around in Git. This resource does a good job of getting your hands dirty with Git. It starts easy, then quickly escalates in difficulty. Maybe wait to try this one until you are feeling confident in your progress and up for a challenge.²

On the other end of the spectrum, Git - The Simple Guide is among the most concise and useful references I have come across. I recommend keeping it open in your browser as you follow along.

We will also need a dedicated text editor, and not a word processor like MS Word, Google Docs, or Libre Office. Initially, this guide was built around the Atom editor due to its widespread popularity and its built-in graphical user interface (GUI) for Git. If you don’t already have a favorite text editor, it does a lot to ease the transition to plain text writing.

Though we will be working in the command line, you will probably find it helpful to download a GUI for Git. This will help you visualize the changes we will make to our repository and ease troubleshooting if issues arise. I like GitKraken for my GUI, but Git Cola, gitk, and Tower are also popular choices.

If working in the command line is intimidating, A Non-Nerd’s Guide to the Command Line is a friendly introduction for the complete novice and quite useful. The Command Line Crash Course by Zed Shaw is a deep-dive into the subject that doesn’t require any previous experience.

My Writing Process #

One of the ways I keep my writing life happy and productive is to always have something to revise. The source material could be anything: reading notes, found text, or writing exercises are the most common.

Of all the approaches, procedural writing exercises are my favorite. They allow me to work quickly and intuitively with found text and software. I play with the language until the piece begins to talk like a poem, then set it aside. Sooner or later, I will stumble across the piece, and I will not recognize it as something I wrote. Sometimes, the poem will require little to no editing. In other instances, it will sync up beautifully with another project.

Before Git, it was difficult to keep track of source materials, references, and revisions, as well as explanations on why I made certain decisions during the writing process. Now that I write with my projects under version control, this is no longer an issue.

Four Commands to Know: commit, diff, branch, and merge #

Understanding just four commands allowed me to effectively use Git in my writing workflow. If you can write a good commit message, compare edits and discrepancies between versions of a file, and modularize drastic changes, you will reap the benefits.

commit #

The most important habit to develop while learning Git is also the easiest: write good commit messages. After you have made a series of revisions to a document, you need to “stage” the file in Git (git add) and then commit those changes to the repository. The repository (or repo) is the database that Git uses to track files and their respective changes.

It can be tricky to wrap your head around the differences between saving, staging, and committing a file. Atlassian has a great explanation. Ignore the parts referring to SVN—this is a competing VCS.

Many of the articles listed in the References section below will go over what makes a good commit message. I have found the template in Jacob Herrington’s How to Write Useful Commit Messages to be the most straightforward. His example pertains to writing code, but his template is very useful for writers.

Summarize the change in fewer than 50 characters
(Use a present tense verb where appropriate)

Because:
- Explain the reasons you made this change
- Make a new bullet for each reason

Explain exactly what was done in this commit with more depth than the
50 character subject line.

Include any additional notes, relevant links, or co-authors.

This is a good starting point, but over time you may find yourself riffing on Herrington’s template. Also, not every commit message will require all of the information outlined above.

Naturally, the creative process is seldom an orderly one, but there are ways to fix that.³ For now, let’s pretend that we always know what we are doing and why, even if we don’t always bundle our revisions into neat, logical commits.

As you get more comfortable with Git and commit messages, start paying attention to how you organize and phrase your commit in the first place. Creating logical, explanatory commits that are organized around a task, problem, or new content is difficult. It requires a systematic approach to your workflow. Try your best. Be patient and kind as you strive towards mastery. With time and discipline, the creative process can coalesce towards order.

diff #

Between staging a file (git add) and committing it to the repo (git commit) it is useful to take a closer look at what changes will be included.

The git diff command compares changes to our repository. For our purposes, we will just use it at the most basic level to see our most recent changes. This only scratches the surface of what diff can do.⁴ Once you have more of a foundation in moving around in Git, tagging commits, and using the git log, there is a whole world to explore. For now, playing around in the GUI of your choice will show you some of what diff is capable of.

branch and merge #

Branches are central to working collaboratively in Git. Branches allow programmers to work on specific features or to fix problems in isolation from the rest of the project.

It is also a place to try out a crazy new idea that you want to try. Add a subplot, switch tenses, work on whatever strikes your fancy. If you are satisfied with the changes, awesome. If not, you can abandon them and your master branch is left unaffected.

When the new edition or edit is complete, you can merge the branch into the main repository.

Extra Credit: git status and git log #

The git status and git log commands will help you keep track of where you are, what has changed, and whether or not your actions have worked out the way you want them to. Lorna Mitchell explains the commands’ usefulness in her talk Advanced GIT for Developers. Both commands are covered extensively in her Git Workbook.⁵ Lastly, once you are comfortable with git status and git diff, give git status -v [filename] a whirl. It will print a status and diff report, side by side!

Write with Git #

Step Zero: Install, Config, and Init #

This exercise assumes that you have installed Git. If you have not, Git - The Simple Guide will get you started. In the exercises that follow, when you see the $ followed by text, those are commands for you to type in or copy into your terminal prompt. You do not need to include the $.

If you haven’t done so already, enter the following into the terminal to setup your Git configuration (making substitutions where appropriate).

In the following example, I took the liberty of setting up Atom as Git’s core editor. For a full list of common text editors, visit Pro Git.

Also, Windows users might need to include the full program path to their editor of choice. As always, Pro Git has the answers.

$ git config --global user.name "Jane Doe"
$ git config --global user.email janedoe@example.com
$ git config --global core.editor "atom --wait"

Now, create a folder called workflow-example in your Home directory. Create and save an empty file called poem.txt in a text editor or in the command line.

$ cd workflow-example/
$ git status
$ git init
$ git status
$ git add poem.txt
$ git status
$ git commit
  - Type "First Commit" for your commit message and save.
$ git status
$ git log

Step One: Source Material #

The first step in generative or procedural writing is to find rich source material. I began with the article The Differences Between Warren and Sanders Matter by Franklin Foer in The Atlantic, but any news article will suffice. Find a paragraph that interests you and copy it. I chose the paragraph beginning with, “If Warren wanted to define herself …” Paste the paragraph into poem.txt and save.

Return to the terminal, and make sure you are still in your workflow-example directory.

$ git status
$ git add poem.txt
$ git diff poem.txt
$ git commit

Alright, let’s write an excellent commit message based on our template.

Source: Differences Between Warren and Sanders Matter

Because:
- Idea Words
- Current Event
- Tab

Reference:
https://www.theatlantic.com/ideas/archive/2020/02/differences-between-warren-and-sanders-matter/605971/

Author:
Franklin Foer

Step Two: Make a Revision #

Point your browser to https://appliedpoetics.org. This site hosts tools to mangle, distort, and otherwise mine source texts. I used the Lipogram function under the Oulipean menu with the constraint of the letter A. Play around for a few minutes, but try to find something that resonates with you without thinking about it too much. Copy and save the resulting text into poem.txt.

Open the terminal.

$ git status
$ git add poem.txt
$ git status
$ git diff --color-words poem.txt
$ git commit
  - Write a good commit message based on the template.
    - Reference https://appliedpoetics.org.
    - Make note of the constraint you used and why.
    - What do you like about the text?
    - What would you like to change?
    - What other directions could you see pursuing?
  - Save your commit message and close.
$ git log

Step Three: Enjamb #

Make some line breaks. Move text around. Look at the original article and see if the algorithm stripped away words you want to keep. For instance, I was sad that mitigated didn’t make it through. So, I put it back in. Save your file.

$ git status
$ git add poem.txt
$ git status
$ git diff --color-words poem.txt
$ git commit
  - Write a useful, clear, and concise commit message
$ git log

Step Four: Add More Voices #

Okay, this is starting to look like a poem. Mine is pretty one-dimensional, but I like the tone. A big problem is that it is very abstract. A good poem needs imagery, texture, and musicality. Let’s try to add some more interesting language to the mix, shall we? Literary criticism is a great resource for cut up materials because criticism contains a diverse array of primary texts and theory.

If you are coming back to your project after a bit of a break, remember you can pull up git log to take a peek at your comments. Fortunately, we write good commit messages!

I chose a review of Marianne Moore’s New Collected Poems, “Willing to be Reckless” by Ange Mlinko. Moore is famous for revising her poems for decades after their initial publication,so she’s a poet who would have loved a VCS. Mlinko quotes and discusses Moore’s “The Chameleon” at length, which will lend musicality and strong imagery to our work-in-progress poem.

Use “Willing to be Reckless” or find your own text. Whichever you choose, pick something longer than just a paragraph. Head over to https://appliedpoetics.org. Find a function you like. I chose “Coloring Book” under the “Pop Culture” menu.

Make a new file, such as reckless.txt, copy the generated text, and save. Run git status in the terminal.

Now, let’s create a new branch to compartmentalize the changes we are about to make.

Step Five: See the Branches for the Trunk #

So far, we have been working on a single branch on our Git repository, the default or “master” branch. Git makes it easy to experiment with new features, story arcs, rhyme schemes, or bug fixes while keeping the original document intact. Once we are satisfied with our experimental branch, it is simple to merge our changes into the master branch. Though it is beyond the scope of this tutorial, it is even possible to pick and choose specific commits from different branches and merge them into the master branch. Pretty powerful stuff! This also allows for multiple editors or authors to work in parallel with each other through an external repository.

There is no rule against working on the master branch while working on the feature branch. In fact, Git was designed to facilitate multiple contributors working independently and simultaneously on the same files.

Sometimes, when we merge branches, a merge conflict will occur. This sounds scary, but it is pretty easy to fix, especially with a GUI. Git Tower has an excellent article on how to deal with merge conflicts. We are currently working with a simplified workflow to avoid these merge conflicts. ⁶

Okay, fire up the terminal.

$ git checkout -b reckless
  - This creates a new branch named reckless and switches to it.
$ git add reckless.txt
$ git status
$ git commit
  - Be sure to note your reference material and generative tactic used.
  - How do you see the "base" poem in light of your newly generated material?
  - How will you shape this new text?
  - How will you revise the old?
$ git log

Congratulations, you have now made a new branch! Now let’s start playing around with our new source material. As before, edit reckless.txt and play around with line breaks until the computer generated text has the look and feel of a poem. Try to work quickly and intuitively. Once you are satisfied, save your file.

Let’s add this file to our repository.

$ git status
$ git add reckless.txt
$ git diff --color-words reckless.txt
$ git commit
$ git log

If you create a file on branch b, when you switch to branch a the new file will not be there unless you merge the branch or pull the file. It can be confusing at first, but this is a feature and not a bug.

If it ever seems like a file has disappeared, be sure to check your branches. This is another case where having a GUI will help.⁷

When you are comfortable, try an experimental repo with weird branching. Like a calendar house, or memory palace, or a journal with a new branch for each day of the week.

The common advice is to “branch early and branch often.”

Step Six: Merge with Master #

In your text editor, combine reckless.txt into poem.txt. Save the file, make sure you are on the reckless branch, stage it, compare changes, and commit. (You’ve got this!)

When you find yourself 75% happy with the poem, stop. Immediately. Stop right at the point where changes begin to make things better and worse. Stop when you can glimpse the perfect poem just around the corner, but it is starting to slip through your fingers.

Write a detailed commit message describing what you want to change, can’t figure out, what annoys you, and what you love.

Now shut down your computer, go for a walk, and do everything you can to forget the poem. One day, in the near or distant future, the poem will resurface. It will have blossomed into a mysterious signal from a distant star. Thanks to our wonderfully written commit messages, we have the best of encountering this bizarre artifact unadorned along with a full background of our intent, allusions, and references.

Before we go, let’s merge into our master branch, shall we? That way we don’t lose our file on an orphan branch. Open the terminal and begin.

$ git checkout master
$ git merge reckless

Pump your fist in the air!

You wrote a poem and learned some Git! Your life is forever changed.

About Me #

I am a technical writer, poet, and a wine and spirits industry professional. If I am not dancing to Sun Ra with my toddler son, I might be cooking dinner or messing with my Emacs configuration. Sometimes, I make time for writing and Taoist mediation.

Thanks, Michael

The Poem #