Take the 2-minute tour ×
Super User is a question and answer site for computer enthusiasts and power users. It's 100% free, no registration required.

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.

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.

Since I work alone, I won't ever be branching or merging---only committing as I go, and occasionally referencing an older version of a file.

What are the best practices for using version control to manage a solo author's writing workflow?

I'm on OSX and I'm planning to use either Git or Mercurial (still deciding which one).

  1. Should I version-control my entire Documents folder as a single repository? (It contains subfolders like Documents/stories/anguish/characters/, Documents/stories/anguish/drafts/, Documents/stories/anguish/brainstorming, Documents/resume/, Documents/letters/, etc). Or should I create separate repositories for each project? Or even separate repositories for each subfolder within a writing project (/interviews/, /web-research/, /story-drafts/, etc)?
  2. Are there advantages to having multiple smaller repositories rather than one big one?
  3. Should I still maintain some version of version control myself, manually? Like draft1.txt, draft2.txt, draft2-shorter.txt, etc? Or should I let the version control system do all this for me?
  4. In the past I tried to never delete anything, and instead stashed old files in folders called backups/, archives/, or old-version. Now that I'm using version control, can I feel free to delete files I don't need anymore?
share|improve this question
    
Version control systems are text oriented, not really suited to handling binaries (i.e., your .doc). –  vonbrand Mar 1 '13 at 17:27
    
Funniest of all is that since the dawn of time Office has had its own version control built in. And nobody knows it's there... –  vonbrand Mar 1 '13 at 17:35

4 Answers 4

up vote 2 down vote accepted

Should I version-control my entire Documents folder as a single repository?

I would strongly suggest a repository-per-project approach (Assuming the projects are independent from each other).

Think about it like this: If you're going to look back at a version from 3 months ago of some project - do you also want to get all other projects to the same date? When you want to look at all the changes you made since last commit - would you do it on a per-project, or on the entire Documents directory[1]?

You shouldn't split more than the project-level: Keep your current sub-directories as directories in each repo. This way, a single commit can hold, for example, a change to a draft file, introducing a new back-story for some character, and an update to the biography file of the same character, with this new back-story detailed in it. Later, if you want to remove ("revert") this story, you have a single commit with everything already tied together.

This ability to keep logically-related changes to many files together (With an extra comment explaining the change) is probably the most important argument I have for using a version-control for a single user (Over a simple date-based backup). Later, when I see something strange and ask myself "What was I thinking," it's a very easy question to answer.

A couple more comments, about things you didn't ask:

  • Branching - you might find this useful for "play-testing" an idea - I don't know how common that is in writing. In programming, I might try something that takes many commits, and not be sure it would work out - so explicitly branch feels "safer" than having to revert back to around the time I think I started it.

  • Git (And presumably Mercurial) are mostly designed for source-code; They usually compare files on a line-basis, which probably means whole paragraphs for you. More importantly, if your files aren't plain-text (For example, if you use Word), setting them up to "understand" the changes made is very hard, and might in some cases be impossible. If your version-control system can't see the changes you made, you lose much of its benefits.

[1] You can actually do this on a per-sub-directory basis even if you use a single repo for everything, and it's not a lot more work; But if you're always going to do that, just keep them separated.

share|improve this answer
    
Traditional .doc is little more than a memory dump from Word; current .docx is an XML document (with binary pieces for spice), which is then compressed. Both are binary files, no "lines" or "paragraps" that any VCS can see (at least not without serious help in handling the format; and nobody is likely to write said support before the next "the world is ending" scare). –  vonbrand Mar 1 '13 at 17:30

Should I version-control my entire Documents folder as a single repository?

I would start this way yes. As time goes on if you feel the repo is just too unwieldly you can break it up into a few repos. A single repo would have the benefit of seeing your changes across the entire Documents folder at once. With separate repos you would have to go into each folder to do commits.

Are there advantages to having multiple smaller repositories rather than one big one?

Having smaller repos means smaller size for each repo. If you ever wanted to share some documents it would be easier perhaps if you had a few repos instead of one. Or perhaps a "private" repo and a "public" repo.

Should I still maintain some version of version control myself, manually? Like draft1.txt, draft2.txt, draft2-shorter.txt, etc? Or should I let the version control system do all this for me?

With git you could make topic branches to take a document in different directions.

A--B--C--D--E--F  (master)
       \
        X--Y--Z  (shorter)

In the past I tried to never delete anything, and instead stashed old files in folders called backups/, archives/, or old-version. Now that I'm using version control, can I feel free to delete files I don't need anymore?

git will smartly store every change you have ever made to any file. So if you want to go back a day or year you can. If for some reason you need to delete a file you could

git rm draft1.txt
git commit -m 'remove unused file'
share|improve this answer

Should I version-control my entire Documents folder as a single repository? (It contains subfolders like Documents/stories/anguish/characters/, Documents/stories/anguish/drafts/, Documents/stories/anguish/brainstorming, Documents/resume/, Documents/letters/, etc). Or should I create separate repositories for each project? Or even separate repositories for each subfolder within a writing project (/interviews/, /web-research/, /story-drafts/, etc)?

Normally you create one repository per project, but for your case I don't think it matters. Basically if you're the only one who's ever going to be working on it all (you're not sharing parts with other people), then one repo is probably fine.

Are there advantages to having multiple smaller repositories rather than one big one?

Mostly, stopping disasters in one repository affecting another :)

Should I still maintain some version of version control myself, manually? Like draft1.txt, draft2.txt, draft2-shorter.txt, etc? Or should I let the version control system do all this for me?

Definitely the latter.

In the past I tried to never delete anything, and instead stashed old files in folders called backups/, archives/, or old-version. Now that I'm using version control, can I feel free to delete files I don't need anymore?

Back up the whole repo. Store it safely on the cloud somewhere. Make sure you know how to recover old versions as needed.

share|improve this answer
    
I have quite a bunch of separate repositories, of stuff only I will ever use. It makes no sense separating stuff neatly into directories and such just to jumble all together for VCS. Current DVCSs are lightweight and simple to manage, there is little (if any) penalty on having dozens of unrelated repositories. –  vonbrand Mar 1 '13 at 17:33
    
Directories within a repository are no more "jumbled together" than directories outside a repository (and perhaps containing repositories). You could consider DropBox a "single repository". In my case, all my non-programming documents live within it. –  Steve Bennett Mar 2 '13 at 10:30
    
For VCS purposes, there is the current_contents and all _history. –  vonbrand Mar 2 '13 at 11:16

Should I version-control my entire Documents folder as a single repository?

No. For "Can I" question type answer will be not so imperative, but "repository per project" have a lot of advantages

  • Common history for all objects in repository means, that evolution in one project doesn't affect other projects
  • In case of multi-file projects you can easy split and separate files into subprojects (when and if it's needed)

Are there advantages to having multiple smaller repositories rather than one big one?

Manageability, size of (possible) transfers on clone|pull|push, size of each repository

Should I still maintain some version of version control myself, manually?

You can use tags/bookmarks in order to have better memorable|more informative labels, than hash-id, in repository's history for any changeset (for any state of work, in practical terms)

Now that I'm using version control, can I feel free to delete files I don't need anymore?

Yes, if you save repositories of finished work (in some backup-location), you have old result ("files") with added value "full history of changes, not only final state"

share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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