Here it is, my long promised article on Version Control. It’s a big enough subject that I felt it best to split it into five uneven parts. I’ll update these to be links as each part is posted.

Edit 8/15/2012 – This is now available collected into a single ebook for your kindle. Only a buck. Version Control for Authors

• Part I: What is Version Control and Why Should Authors Care? <- you are here
• Part II: Getting Started
• Part III: Get Your Stuff Back
• Part IV: Questions & Tips
• Part V: Addendum

Part I: What is Version Control and Why Should Authors Care?

Authors vs. Programmers

I’m an author that moonlights during regular daytime hours as a programmer. For the purpose of this series of articles, I’m going to assume that you are not a programmer, and that furthermore, you don’t care about programming concepts or lingo. I’ll do my nerdy best to leave out the tech term. The reason for throwing this disclaimer up first thing should be clear in about two paragraphs.

What is version control?

Here’s the deal. As programmers add features to software, they often break stuff that used to work. This is because programmers are so smart. Also, often several programmers are working on a single piece of software at a time, and on different parts of the software. A programmer wants to be able to test his wonderful new features without having to wait for the other programmer to finish the new feature he is working on.

To help combat these (and other) problems, programmers came up with version control systems. These systems allow programmers to keep a running diary of all changes to a program. They also allow a programmer to work on a specific part of a program so he doesn’t have to worry if his co-worker is currently breaking another part.

How do these “version control” systems do this?

Programmer magic.

Ha ha. I got you. Programmers do not perform magic. We leave that to hardware designers.

Where was I?

Oh yeah, what are version control systems? To make it clear let me suggest an analogy. Better yet, let me proclaim an allegory.

The Allegory of the Library

There is a library. Steve walks up to the library and asks the librarian for copy of “Raising Vegetables.” The librarian hustles back to the shelves and runs the book through superfast photocopier then gives that photocopy to Steve. Steve notices that the book doesn’t have a chapter about asparagus, his favorite vegetable. So he writes one.

The next day he returns to the library with his asparagus-added version of the book and hands it to the librarian. The librarian flips through it and sees the added part. From now on, the librarian makes sure that when people ask for a copy of the book, they get the asparagus chapter as well.

A month later Steve and Trisha go to the library (Separately. They’re not on a date or anything.) and each asks for a copy of “Raising Vegetables.” The librarian runs two new copies and hands one to each of them.

At home, Steve adds a new chapter, this time on his second favorite vegetable, arugula.

At the office, Trisha is reading the book and sees that in one place it has the word “carrion” where it obviously meant “carrot.”

The next day both Trisha and Steve bring back their respective copies of the book. Trisha get’s there first. The librarian notes that she has changed “carrion” to “carrot.” All future copies will now say “carrot.” Then the librarian picks up Steve’s copy and reads through it. The librarian notes that his book still says “carrion”, but knows that Trisha’s version changed things for the better. The librarian does not change the master copy back to say “carrion.” Then the librarian sees and adds the chapter on arugula.

Years later, a pumpkin supremacist named Kip comes in and demands a copy of the book before it contained information about asparagus. The librarian keeps good records, so he runs back an makes a copy of the pre-Steve edition.

And they all lived happily ever after.

In this allegory:

• the library is like a version control system.
• Steve and Trisha and Kip are like programmers
• “Raising Vegetables” is like a piece of software.

That’s a long way of saying it, but the version control system’s job is to keep track of every change that is made to the code.

I think that dead horse has been beaten enough, so let’s move on.

Why would an author even care?

Perhaps you don’t yet see how all of this might affect you.

“That’s great,” You say, “But why does a mild-mannered sanitation engineer like myself care about this miraculous solution to a problem that only the nerdiest geeks have? I just want to write the great American novel.”

I’m so glad you asked.

Here are some reasons why an author might want a version control system of his very own. In other words, here’s why you might want to keep a history of every version of a piece of fiction.

1. You want to compare your first draft to the final draft.
2. You have lost part of a story before by accidentally deleting a large chunk, saving the file, and then closing the program.
3. You have ever accidentally copied an old version of a story file and replaced the new (correct) one.
4. You aren’t sure about editing out a character and it would be an obscene amount of work to add her back in if you decide you don’t like the change.
5. You are a control freak and need to know that you have a complete history.

If none of these reasons work for you and you can’t think of any of your own, well, then you might as well stop reading this article.

The Basic Process

Here are the steps that you’ll be taking as you begin to use version control.

1. Create a repository.
2. Check out a copy
3. Work/Edit/Write/Create
4. Commit your work to the repository.
5. (optionally) delete the checked out copy.

Create a repository

The repository is like the bookshelves in the library. It holds all the data that you want to keep track of.

Check out a copy

You don’t work on the repository itself. As a matter of fact, many version control systems won’t even let you try. The one I’ll be showing you later is among these.

What you do instead is check out a copy. You pick a directory and tell your version control system “I’d like a copy of my repository in this directory.” The version control system then goes to work.

After you check it out we’ll be clever and call it your “Current Working Copy”

Work/Edit/Write/Create

Now you do that literary voodoo that you do so well. Even though I’ve listed several steps, this is where you’ll still spend the bulk of your time.

Just make and copy files into the folder that is your current working copy. Then you can edit any of those files.

Commit

This is where you bring back your updated work to the library (repository) and the librarian saves a new version. Programmers call this process a “commit.” However, unlike the allegory above might suggest, you get to keep your working copy. It isn’t deleted or anything. The “librarian” just looks through it and updates anything that needs to be updated in the repository.

Delete

If you are the only one working on a story you don’t need to delete your current working copy. If you are like most authors and working alone on a project, you can just repeat Steps 3 & 4 rather than 2,3,4, & 5 every time you want to work.

Don’t worry if you do delete it (after you’ve committed it, of course.) You know you’ll always be able to check out the latest version from your repository.

Overwhelming tools

Let’s just pretend that now you’re sold on the idea of being able to use a version control system for your writing. Now you just need to find software to do help you, because it sounds like an awful lot of extra work if you’re going to do it “by hand.”

There are tons of revision control programs out there. Just bring up the Wikipedia article for “List of revision control software.” Some are paid, some are free. Some require a separate server program and some don’t. Some are difficult to use, some are easy. Some are command line only, and some have cutesy graphical interfaces.

How are you going to know what is strong but simple enough that you’ll actually use it?

Well, I’m going to tell you.

 

…In Part II. (tomorrow)