20

I'm a writer, not a programmer. I'm just now for the first time learning about version control and how it works, and I am wondering how version control could streamline my workflow.

In a previous question, I asked what version control system to use, and settled on Git.

For years, I've used my own cobbled-together version of version control. My folders are littered with files like resume-2012-06-01.doc, resume-2012-06-15.doc, letter.txt, letter-old.txt, letter-v2.txt, story-notes.txt, story-notes-with-character-sketches.txt story_draft1.txt, story_draft2.txt, story_draft2-shorter.txt, etc.

Now that I'm using version control, I guess I don't need to manually create all these renamed versions of a file. What should I do instead? Now that I'm using version control, how should I name my drafts and rewrites? How should I keep track of drafts and revisions?

What philosophy and practices should a writer use for commenting when doing a Git commit of rewrites and revisions to keep track of everything and find things easily later?

20

There are two concepts in git that can help: branches and tags.

Tags. Think of a tag as a name for a specific revision. Any time you want to remember a version, create a tag for it. For example, when you finish a draft, you can tag it like this:

git tag first_draft

When to use tags. Tags are good for marking any version that you might want to remember later. I use them to mark the end of each draft.

Branches. Think of a branch as a series of changes. The default branch is called master. That's a good branch to use for your initial research and first draft. Unless you create a new branch, every change you make updates the master branch.

When to use branches. Whenever you want to start on a new series of edits, you have a choice. You can either continue on the the current branch, or create a new branch.

Some possible uses for branches:

  • Drafts. You might start each draft by creating a branch for it. (I tend not to do this, but it may suit your needs.)

  • Experiments. Suppose you want to experiment with rewriting a few scenes to change from first person to third, or to change the POV character. You can create a branch and do your experiments there. Later, if you like the new POV, you can continue writing on your experimental branch. If you don't like the POV changes after all, you can switch back to whatever branch you were on before.

  • Submissions. Before I make a submission, I'll often create a new branch, add my cover letter, make any minor manuscript changes specific to that recipient (e.g. quirks of mss formats), and add a text file with notes about the submission. When I receive a reply, I can check out the branch and update my notes.

I tend to use branches more for experiments and submissions than for drafts. When I finish a draft, I'll tag it, then continue with the second draft on the master branch.

Creating branches. To create a new branch, use the git branch command like this:

git branch charles_pov

When you create a new branch, the new branch starts with the same content as the branch you were on. If you're on the master branch and you create a charles_pov branch, the charles_pov branch starts with the current content of the master branch.

Note that creating a new branch doesn't switch to the new branch. To switch to a branch, see below.

Switching branches.

You can change branches at any time by "checking out" a branch. To switch to your new charles_pov branch:

git checkout charles_pov

When you commit changes, git updates whatever branch you are on, and leaves the other branches unchanged. So if you switch to the charles_pov branch, your changes will update the charles_pov branch, and the master branch will remain unchanged.

Creating a branch and switching to it in one command. You can create a new branch and switch to it in a single command, like this:

git checkout -b charles_pov

Viewing tags and branches. You can see a list of all tags and branches with these commands:

git tag
git branch

Checking out a tag (AND A WARNING). Remember that a tag is a name for a specific version. If you've tagged each draft, you can check out an old draft like this:

git checkout twelfth_draft

Yep, you check out a tag the same way you check out a branch.

BUT NOTE that when you check out a tag, you are no longer on any branch. Any changes you make end up in a floaty nebulous place that I don't know how to explain succinctly. Git does warn you about this.

The current branch. To see what branch you are currently on, use this command:

git branch

Git displays all of the branches, and marks the current branch (the one that will be updated when you make changes) with an asterisk.

  • 4
    One thing I would add: use meaningful checkin comments. (I assume git has checkin comments.) Later when you're browsing the revision history looking for, say, where you introduced a new major character, these comments will save you lots of time. There is no virtue in terse checkin comments. – Monica Cellio Feb 17 '13 at 3:04
  • 1
    git has checkin comments. The first line of the comment is treated as a title or summary. Some parts of git display only the title, and only the first 50 characters of the title. So it's best if the most important information appears in the first 50 characters. But after the title line you can write a detailed description of any length. – Dale Hartley Emery Feb 17 '13 at 22:19
  • Note: Software version control such as Git is designed to ease collaboration on shared, mergeable program files. Historical features are largely intended for investigation into what changed in code, serving the pursuit of the cause of a bug. Which is to say you can institute policies described above to do what you want, but the system is not explicitly designed for the use case of "story version control." You might have multiple trunks to represent distinct versions. Starting a new folder for a large work when you switch phases can make it easier to "go back" & inherently creates snapshots. – Kirk Mar 14 '18 at 16:09
6

Just to play devil's advocate a little bit, I think a case can definitely be made for not using a software version control tool in writing.

As a writer who also works in the software development industry, I have some pet theories about this, though I am still experimenting myself.

In 1967, a computer programmer called Melvin Conway coined what has become known as "Conway's Law": "Organizations which design systems ... are constrained to produce designs which are copies of the communication structures of these organizations."

This basically means that a piece of software is very probably (or even inevitably) going to come to resemble the organization that created it. This happens because software (like writing) is "soft" and a piece of functionality can be achieved in many ways, so a software engineer is inherently more limited by the organization they work for than the tools they use.

I have a corollary pet theory that the tools used in writing will inevitably influence the nature of the work produced with them. You might say "so what?" After all, version control systems designed for software development are wonderful and powerful tools that allow sometimes hundreds of engineers and developers to collaborate effectively. I would say "exactly".

Good writing has a different end goal than good coding. (I'm not talking about technical writing or documentation, but prose). Prose writing is intended to create an intensely personal, one-on-one experience between the author and the reader (who is usually trying to relax and escape from a chaotic, fast moving world with a time consuming but enjoyable book). The product of the writer's work is directly exposed to the reader (or end user) unlike a piece of software where 99% of the time the code a developer writes is obscured underneath an abstraction layer of a visually-based UI (user interface). In almost any software application, the user's enjoyment of the application is totally unrelated to the quality of the code in the business layer. If the code is sufficiently well written for the application to be functional at all, the experience is the same to the user if it is incomprehensible spaghetti code or beautifully minimalist, well commented art. This is absolutely not the case for a writer.

So the point of something like Git is to collect and preserve code and allow trace-ability and change control. It accumulates changes in code from multiple developers or a single developer over time and allows you to do things like deliver a change set, realize that you screwed up the whole application, and undo your change, or even integrate part of it. The point is to preserve the functional state of the application, not the cohesive "voice" of the code. Code doesn't usually have any cohesive "voice", particularly in cases where a large team has collaborated on a project. So if you use version control to write a novel, you will be encouraged by the tool to maintain multiple versions of the novel simultaneously, change parts back and forth between versions, keep every single word you have written somewhere and be able to reinsert them, and create an ever-expanding living document with no end state. A software application is continually being rewritten until it is abandoned. Every time there is a defect ticket, an update to something the application depends on, an update to a browser that uses the application, or any new delivery of functionality, there will be changes to code somewhere. The only static and unchanging software apps are dead abandonware. A novel is totally different. You have to edit the novel and shape it into a final, immutable form that will not change. Even though it is possible to have an ever-changing novel delivered to a device like a kindle, readers don't want that. They don't want to have to go back in a book they are already reading and find new changes back in chapter 2 and try to integrate them into their understanding of the story. Readers want a book to be finished and static before they start to read it.

If your tool is encouraging you to be verbose, keep potentially infinite versions of a story, and never need to reach a finished state, I think a lot of writers, particularly less experienced ones who might have a tendency to be too verbose anyway would be more likely to write gigantic "ball of mud" novels that are ultimately unreadable. I say that as someone whose first novel fits that description.

Writers have always had some connection to the tools they use, which is why people still associate novelists with clickety-clackety typewriters. The tools constrain us and force us to have our end state in mind before we put words on paper. Hemingway wrote long hand in an age of typewriters and plenty of more modern authors used typewriters in an age of computers. It isn't about being a Luddite, it's about the psychological impact of knowing that what you put on the paper is somehow immutable and can't be easily undone. It forces us to be concise, to choose words carefully, and do more writing in our brain and less in the tool. Version control encourages more writing in the tool and less in our brain. I think we have already seen an avalanche of bad writing in the age of word processors, and version control might be a step too far down the wrong road when it comes to prose.

So to answer the question: Maybe don't.(?)

  • 1
    I like this answer; but as a fellow software developer I think there's another level here you didn't acknowledge: Software Development Lifecycles. Version Control is just that, a history of changes. The life cycle is often what gives the process structure and gets you to a release. While the VC system, aka git, may not be particularly well formed to the use case of writing a novel, it should be possible to have a "Writing Development Cycle" layer on top of it that gets around the problems with the VC system. That doesn't invalidate what you wrote, but even VC's aren't good enough for SDs. – Kirk Mar 14 '18 at 17:02
  • 1
    @Kirk I agree. A writing life-cycle with a planned release would seem to be inevitable in order to use VC for novel writing, even if the cadence is informally kept in the author's head. I'm also sure that some people will immediately come back with "I use VC for prose writing and it works great". It's always dangerous to generalize about tools, since so much depends on the person using them and what they are used to. I do think there is a pattern of influence back from our tools to what we make with them though. – JBiggs Mar 14 '18 at 17:08
  • 1
    Totally agree. The real answer for any person probably lives between the two present here. There's value in challenging using these tools for writing and it will be to someone's benefit that you did it – Kirk Mar 14 '18 at 17:38
  • The main effect of using version control on my writing is that I have some rudimentary documentation of my progress (commit messages). But then, one might argue that I'm not really using version control, as I basically use it as backup/syncing tool. – celtschk Aug 23 at 7:20
2

I do not know whether the sophisticated functionality of git would be all that useful, unless perhaps if you are collaborating with another writer. However git does offer a couple of things that are potentially interesting or useful to the writer.

The first, and somewhat trivially, is that it neatly does the book-keeping versions of your text for you, without bothering you about which names are which, or wondering if you are editing the correct version. So you could just stay on your master branch, commit your changes daily, but always deal with files like Chapter01.md. Its versioning without the clutter.

More intriguingly perhaps, is that when you commit, you are invited to add a comment describing the commit. Programmers use it to indicate the nature of the change being made (e.g. 'Fix one-off indexing error'), but more pertinent to the writer might be a reflection on what was written, a sort of writer's diary that you keep as you go along.

  • Welcome to Writing.SE Jacob, glad you found us. Please check out our tour and help center. – Cyn Aug 23 at 6:03

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.