#noteworthy

Useful Features of Version Control Software

This is a follow-up to my earlier post entitled Version Control for Writers.

An article called " Git Foundations " has done a lot for me, to help explain the concept of version control, from the point of view of a writer. I’m testing out some different ways to use version control for my writing, but first I’d like to describe some of the basic concepts. (For a description of the basic commands, for a common form of version control, take a look at Git for the Lazy .)

I’m writing this for two audiences. First, for writers who might want an explanation of the value they might get from using version control software. Second, for programmers, who might want to understand the contexts in which a writer might use the tools they’ve built.

I’m new to this so, please, if anyone notices any mistakes or confusing bits, please point them out. My hope is that once I properly understand the features, I can apply them wisely.

Features

I’ve learned that these are the basic features of most version control systems. I’ll describe each in terms of how I think it would be helpful for writers. In some cases, this might differ a bit from the original purpose of the functionality.

Repository
For a writer, it might be easier to think of this as your "project." It's basically a group of files and directories related to a thing that you're working on. As you work, you might add to your files, add new files, delete files, rename them and so on. Version control can help you to keep track of the history of these changes as you go. Your repository will also contain the archived, previous versions of your project, along with information about the changes you made over time. It can also help you to undo changes, or to merge things from one version of a file to another.
Commit
You may also hear this called "snapshot." To commit is to store the current contents of the project, along with a log message from the user describing the changes. I think that for a writer there's a difference between "hitting save" and "taking a snapshot." Many of us hit save all the time, but that doesn't mean we've hit an important milestone. The nice thing about a commit's log message is that, when we're ready to commit, we can also make a note of what it is we were working on. Example messages might be: "I fixed all the verb tense agreements" or "I changed a character's name from Darby to Darcy" or "responded to editors comments from an e-mail I got yesterday." These log messages can go a long way to help explain the archive, for later use.
Working Files
These are the files you're currently working on, as opposed to some previous or alternate version of the files. Those are saved elsewhere in your repository.
Branch
Any copy of your project is called a "branch." Your working copy of a project is a branch. Let's say you want to start working on a second edition of your book: that's a "branch" of your book. Your old first draft: that's a branch, too. Your editor's marked-up copy of your text is a branch. Version Control can enable you to move from branch to branch, like the smart monkey that you are.
Tag
Any copy of your project is called a branch, but a "tag" is a special "version." In the computer world a tag is named with a version number like 1.0 or 2.2.5. For a writer, it might help to think of this as a "milestone" for an unpublished work or even an "edition" for a published work. For example, perhaps you sent a manuscript off to an editor to be considered for publication. That copy is a special version, or tag . Nevertheless, it may not get published and you may want to keep working on a new copy or branch of it, while it is being considered.
Diff
Remember in English class when your teacher gave you two poems, asked you to read them and to write an essay to compare and contrast the two? Perhaps in a more advanced class, you were given two drafts, editions or translations of the same text and asked to do the same? In those later cases, the differences can be quite granular sometimes. Lucky for us, the programmers have already devised tools that make it easy to do the compare/contrast, without having to re-read both versions and without writing a whole essay about it. The differences can be clearly marked for your consideration. Some word processors already know how to compare one document to another but Diff can also compare groups of files to each other.
Merge
You've given out six copies of your draft to your writer's group. Each member of the group made different marks on a different copy (or branch ). Now you have to combine the edits, or not combine some of them, into the working copy of your project. With the help of diff this can be done more efficiently: when there's a change you want to adopt, you can merge it into your working copy.

Limitations

Both word processors and version control systems have some limitations.

Track Changes and “Save As"There’s a lot more information online about the limitations of Microsoft Word and the limitations of word processors in general , but for now, suffice it to say that they only have very simple version control abilities: you can track (linear) changes, and you can “save as” and you can compare up to two different versions, but without much information about the relationship between them.Text-OnlyThe version control functionality described above works best on files that are text only. (There are exceptions to this, but I don’t understand them yet.) The files your word processor saves by default, although they contain text, are not stored in a text-only format. I venture to guess that 99% of writers aren’t willing to give up their word processor and its format, which is often required of them by their editors and publishers. For more about this limitation, read The Limitations of GitHub for Writers .

Next Steps

My goal is to find a workable, user-friendly way to use these powerful tools as part of my writing process.

This week I’ve been experimenting with different tools designed for version control. I’ve tried two of them, Flashbake and Git-Annex Assistant. I’d like to describe my experience with these, from a writer’s point of view.

Once I understand the basic features, then I’ll post about the different types of users who work with electronic documents, including writers, editors, publishers and archivists. Then, I can try to measure: how well can the features work for these users?