Tip for Writers and Novelists: Use Subversion to track changes in your work!

As a developer, I take some things like version control for granted.

Recently, I suggested version control to my wife to make it easier for her to compare her current revisions with earlier revisions.  Currently, when she wants to make a new revision, she creates a new file with a different filename.  This doesn’t give her to Word comparing or change tracking.  So, if she deleted a paragraph two, three, or twenty revisions ago, she could easily go back to a draft containing the paragraph and retrieve the text or compare against the current revision.  It would even be possible to check out the earlier revision!

On top of change tracking, a subversion repository offers a complete backup of documents.  This would be excellent for someone who is worried about losing their documents.  For instance, you can create a subversion repository on an external hard drive and you’ll never lose anything earlier than your last check-in.  Granted, you have to adopt the version control process, but the benefits greatly outweigh the possible headaches of having no sort of version control or revision history.

For any writers who may stumble across my site, this post will walk you through setting up a local subversion repository for free.

Required Download: TortoiseSVN

My version of TortoiseSVN is 1.6.6.  Although your version may be slightly different than the screenshots, the overall steps should remain the same.  After installing TortoiseSVN, be sure to reboot your computer to make sure the svn caching mechanism is working. Then, continue reading…

Step 1: Creating a repository

Since my computer has a flash card reader, I’ll be building my repository on a 2GB SD card.  I don’t really recommend creating a repository on flash media if you plan on creating and checking in many drafts regularly because there is a maximum number of writes available to flash media.  Use an external hard drive and you’ll be set.

Browse to your external drive and create a folder called “svn_repository”.   This is where your committed drafts/revisions (think of these as “checkpoints”) are stored.  This also acts as a backup in case you accidentally delete your writing folder or any file within the folder.

Right-click on the “svn_repository” folder and choose TortoiseSVN -> Create Repository Here

TortoiseSVN - Create Repository Here
TortoiseSVN - Create Repository Here

You will receive an informational popup that says “The repository was successfully created” or something very similar.  Hit OK.

Step 2: Create a directory to store your writing content

Now that you have a repository ready, create a new folder to use for your writing.  To make things simple to follow, I’ll create C:/Writing but you can create the folder on your Desktop or your ‘My Documents’ folder or anywhere else you would like.

Once you have identified your content folder, right-click on the folder and choose TortoiseSVN -> Checkout. (Refer to the image above for this option’s location).

This next part is the most critical.  TortoiseSVN asks for a URL of a repository.  This also accepts a file:///URL (URI) which allows us to use the repository we’ve just created on the external drive.

Type in the complete file location of your repository, e.g. file:///d:/svn_repository

SVN for Writers: file_repository

Click OK.  You’ll be presented with a status window which will become very familiar after you’ve used TortoiseSVN for a while.

You should see the message

Command: Checkout from file:///d:/svn_repository, revision HEAD, Fully recursive, Externals included
Completed: At revision: 0

After your “Completed” message, you’re ready to start adding and versioning files.

Step 3: Start tracking your revisions

Navigate to your writing directory (e.g. C:\Writing from above).  Add a Word document to this directory with some content.  I’ve added a document called ExampleDocument.docx.  Inside this document, I’ve added “This is line one of my draft”.  Be sure to save your example document so you can see the magic of subversion version control.

Go back to the directory, C:\Writing.  Right-click on the example document and choose TortoiseSVN -> Add

SVN for Writers: add_file

After adding the file to version control, you must commit the file.  This submit the file to version control as an initial checkpoint or baseline to which you can compare your next version.

SVN for Writers: SVN Commit

After choosing the commit option, you’ll be presented with a commit comment dialog.  I usually enter something such as “Initial document”.  Make sure your document is checked/selected and hit ok.

SVN for Writers:SVN Commit - dialog

Hit OK, and you should be presented with another confirmation dialog ending with

Completed: At revision: 1

Step 4: Make changes and commit
Now, go back to your document and make whatever changes you’d like.  Change some text in the original line, add a few lines.  Just put something in the document that is different while retaining a little of the original so you can see how effective subversion can be for a writer.  Be sure to save the document and close it.

Go back to your writing directory, C:\Writing.  Right click on the file and choose SVN Commit as we did previously. Enter a useful comment such as “Second Draft” and hit OK.  You should now be at revision 2.

Step 5: Compare revisions or drafts

You should still be looking at C:\Writing.  Right click on your document and choose TortoiseSVN -> Diff with previous version
The document should open in Word with change tracking.  I’m using Word 2010, so your view may be slightly different if using Word 2007 or Word 2003.  As a caveat, I have not used subversion for change tracking of documents or drafts in Word 2003.  It should work the same, because I know the tracking changes was available.

SVN for Writers:Compare Result

Step 6: Adopt the SVN commit process
This is probably the hardest step.  In order for this to work, you’ll have to adopt the process of checking in your changes to subversion when you’re done with a revision or draft.  If you’re using an external hard drive, you’ll have to be sure the drive is connected to your computer.

Extras: I accidentally deleted my writing folder!
The beauty of subversion control is that you always have your document structure backed up.  You can also take your external drive along with you and, if the computer you’re sitting at has TortoiseSVN, you can access your current documents and all of your history!  How awesome is that?  As an example, we’re going to delete the writing folder I just had you work so hard to create.  Remember, I’m working with C:\Writing which contains ExampleDocument.docx.  Please don’t go deleting all your life’s work right now and complain that I told you to delete everything.  If you’re unsure whether you’re about to lose a lot of hard work, just take my word for it and don’t delete anything.  You can, however, create another completely different folder if you want to play along.

Now that I’ve deleted my example directory, I’m going to basically follow Step 2 from above and create a new
directory called C:\MyWritingBackup instead of C:\Writing.  Refer to Step 2, and click OK on the Checkout dialog.    You should now see a message like:


Command: Checkout from file:///d:/svn_repository, revision HEAD, Fully recursive, Externals included
Added: C:\MyWritingBackup\ExampleDocument.docx
Completed: At revision: 2

This message is telling you that you’ve pulled your documents from your repository and added your ExampleDocument.docx to the folder because it didn’t exist.  Go ahead and navigate to the document and redo Step 5 from above to be sure your revisions are still available.  See how cool this is?

Extras: I accidentally deleted a file and emptied my Recycling Bin
First of all, what were you thinking?! Seriously, though, how many times have you wished you didn’t delete something minutes after you’ve deleted it forever?  Since subversion is keeping a copy of the file for you, you don’t really have to worry.  If you haven’t yet committed your files, you can just navigate to the folder C:\Writing and select SVN Update. This syncs your folder with the most current folder in your repository.  Just like the above example, it will see that ExampleDocument.docx is missing and add it for you.

What if you’ve deleted a file and committed the deletion?
Don’t worry.  You can retrieve files from any checkpoint!  For instance, I’ve added another file called Others.txt, deleted the first ExampleDocument.docx and committed my revision.  Now, you can right click on the folder and choose TortoiseSVN -> show log

SVN for Writers: Show Log

In the log viewer, you can see all actions from previous checkpoints.  My last checkpoint shows a little document icon with a red ‘X’ to indicate that a file was deleted.  Now, I can select the revision just before the deletion and in the bottom list view, you can see the path of /ExampleDocument.docx.  Right-click on this document and choose “Open”.  Now, you can save this document to your Writing folder and add it back to subversion.

Summary

There are way more awesome uses for subversion, but this should get anyone ready for backing up their files and tracking changes in a really awesome way.