What is the purpose of version control?

If you are one of those rare people who can write, straight through, without any major refactorings or changes of direction along the way, more power to you. But for many people, and IMO any long-running project, source control is a major benefit. Here are some of the reasons:

• When you realize the path you're going down is a bad idea, you can roll back to a prior version (not necessarily the most-recent save). Sure, you could save a bunch of numbered/timestamped files to simulate this, but then you are spending your own mental energy on something that the tool can just do for you. Would you rather be writing or doing administrative tasks?

• Manual "version control" (the numbered-files approach) encourages you to work in one large document (easier to manage). But often you are better off breaking your document down into separate files and creating a master document that includes them all. (And don't forget about any graphics you're including, like diagrams or screen shots; those are files too.) Automated version control makes this no harder than working with one file, but manual "version control" does so you probably won't break it down.

• Source control lets you intentionally branch files to try out a change. If you don't like it, abandon the branch. This is subtly different from rolling back to prior versions; with branching you can focus on one change (remove this character from the novel, replace the running example in the manual, whatever). Rollbacks are usually after-the-fact realizations and you'll lose whatever other work you were doing at the same time; branching helps you to be more intentional.

• Branching allows you to work on changes independently. If you tend to have a lot of idea in play at once, or you have only short bursts of time to work on your document, or you're just very distractable and want to "do all the things" now, source control can help you separate those tasks so you don't end up with half of idea 1 and a third of idea 2 and the bare outline of idea 3 all mixed up together in a document that you now need to untangle because your editor wants a snapshot.

• Most source-control systems have the concept of a label, so you can easily annotate the files for important events like "submitted for first review" or "delivered draft to customer" or "release 3.1". Trust me, if you work on long-running projects, eventually somebody is going to ask you for a copy of exactly what was sent to such-and-such customer a year and a half ago. If you dropped a label at the time, you can do that without having had to archive a copy of everything.

• If you will ever be working with co-authors, or editors who want to directly edit your source documents, source control is essential to avoid collisions. That way you can keep working and later you can merge in your co-author's additions or your editor's changes.¹ (Merging can get messy depending on the type of change, so there's more to discuss here, but that seems to be getting too far afield of your question.)

• Source-control systems have built-in comparison tools, so it's easy to see the differences between your current working copy and the last one you checked in, or those between two previous checkins, so long as you use a suitable format.¹ This helps to remind you of what you changed in this "session", and if you're doing something like addressing review comments, you can compare the comments to your diff to make sure you got them all. Similarly, when you're doing something new, like updating a set of screen shots, you can check to see if you got them all.

• With source-control systems, checkins are (nearly) "free" so you can check in small, granular changes. One thing this does is to limit your risk; if something happens to your current work (cat across the keyboard, misplaced "rm*", etc), you can get back to the last version you checked in. More importantly, though, by reviewing the comments you made on each checkin (do make meaningful checkin comments; it's important), you can easily get a sense of the progression of work, what you've done already, and what remains.

Source control isn't necessarily a win for everybody; I don't bother to use it for blog posts, Stack Exchange answers, short one-off documents, and so on.² And you have to either use an Internet service or set up your own server (non-trivial for most people). But for many projects, and especially if source control is already available (e.g. for the code) and you just need to opt in, it's well worth using. As a technical writer I insist on it, even if I'm (at the time) the sole writer. I have never regretted that. (Granted that I work in the software field so the issue is just access to the source-control system, not setting one up.)

¹ You cannot diff and merge binary formats. This only works if your source is text of some sort, whether that's some XML flavor, HTML, LaTeX, or something like that. Many modern tools can export as XML, but that might not help you -- if your diff tool is sensitive to white space, then each export is likely to change the line wrap so rewriting one sentence could cause the rest of a paragraph to show as different. Check both your writing tool (how it does exports) and your source-control tool (how it handles this kind of variation). I write all my source in a text editor that won't try to "prettify" or format/export for me, and I can merge and review diffs easily.

² Actually, I did use Git a few times for Stack Exchange posts, because they were joint efforts and this made collaboration easier. So even there, occasionally it's helpful.

posted over 10 years ago

CC BY-SA 4.0

Monica Cellio‭ staff

2514 reputation 51 268 361 110