What You “Miss” When Using Version Control

Recently I stumbled over this list about “How I save documents” – it’s German but you’ll surely get the point.

It is meant to be funny, but actually it’s a comprehensive documentation of one of the reasons why using plain text and version control rocks. When presented with this list scholars or other people usually respond with telling sighs of recognition – while my personal recognition has actually faded away and has to be actively pulled from a very distant past 😉

I realized that while having written so much about version control on Scores Of Beauty we don’t have an article yet telling you concisely why you should use it as your bread-and-butter tool for daily work. So today I’m going to give you a list of things you will miss and eventually forget when you switch your toolkit to using version control.

Issues “missed most” when using version control

  1. Naming schemes and file duplication as displayed in the above list
    With version control you will have to content yourself with just one “projekt.doc” (well, it should rather be “projekt.tex” or “projekt.md”)
  2. Asking yourself which copy you should edit or have edited
    With version control you edit the single file. Fullstop. Any modifications are commited to and documented in the project history.
  3. Propagating wrong edits or deletions through shared drives etc.
    Thinking that managing a project on Dropbox or similar service serves you as a backup may fall hard on your toes. If you delete a file while online it will immediately be propagated to the server, and when you are sharing that server with others the files will be deleted from their computers too. If you accidentally delete a file in a version control repository you can simply “discard” that action and revert to the last state. Actually it’s quite improbable that one accidentally deletes a file and commits that deletion to the repository. And even in that case version control won’t finally delete the file but will propagate the deletion as a revertable process.
  4. Concurrent and conflicting edits
    Did you ever run into the issue that your collaborator sent you a document containing some edits. Then you continued to work on that document (respectively a renamed copy, see 1.), and the next day your partner sent the file again, with some more edits? Then you’ll probably be sad to hear that version control takes all the fun out of manually searching the copies for the different changes and figuring out where to apply which version of the content (see 5.). With version control you’ll simply merge in the changes and have the latest state of all collaborators’ work available. And if these changes should conflict in some places, you’ll be conveniently confronted with the decision to choose from the respective version on a line-by-line basis.
  5. Searching for modifications
    Although many programs offer features such as “tracking changes” or similar, in the end all modifications will somehow be melted into a document file. When you look at a document, for example a Finale score returned from a proof-reader, how can you tell where the fixes are? Either you simply trust your colleague, use some external documentation such as a commenting email and trust that, or you have to compare the files yourself again. Version control presents you with the exact changes through the project history, so you’ll immediately (and persistently) know who has changed what and when, usually also why (using commit messages).

Feel free to extend that list in the comments 🙂

Rounding off this article I’ll tell you a real-world story I heard from a member of a well-known publishing house. It makes use of a mix of these aspects.
After ten years of regular use editors of said publishing house reviewed the edition of an opera and did some improvements and fixes to the musical text. Unfortunately someone applied these fixes to the wrong score files, say, a backup copy representing the state of the edition half a year before publication (I’m not completely sure about these details, but the point is true). So the result was a completely faulty edition – but with the latest fixes. Unfortunately they only realized their mistake after having trashed all existing copies of the rental material and having printed 20 new sets (and I can tell you that sets of material for this composer’s operas are big). In fact it was the orchestras who had to notice that their new performance materials seemed crappy and unusable …
With version control the initial mistake could have happened too: it’s perfectly possible doing some work while having the wrong branch checked out, and one would even commit that work to the wrong branch. But there are so many opportunities where it’s usual or necessary to look at the project history that it’s extremely unlikely that this error wouldn’t be noticed before actually producing the paper copies. And fixing the issue itself is really straightforward: As mentioned above all changes are completely documented in the project history, so it’s not an issue at all to identify the modifications that have been applied during the review. Actually you now would not identify the modifications and re-apply them manually to the correct state of the edition, but you would rather take the commits and apply them to the right branch – which is appropriately called “cherry-picking” in version control terminology. Depending of the “distance” between the two base points in the project history this process may in fact produce a number of “merge conflicts”, but these can be handled in a straightforward manner too. And finally the version control documentation will clearly indicate the spots where the edition has been changed, so the responsible engraver will know exactly where she should have a close look to check for any regressions and side-effects.

So, actually the question should not be “Why should I use version control?” but “How could I ever justify not using version control?”

5 thoughts on “What You “Miss” When Using Version Control

  1. Samuel

    Thanks for your post. There are a lot of pros for version control. Wouldn’t it be cool if some basic Git functionality was included in Frescobaldi?

  2. Pierre-Luc Gauthier

    Thanks Urs. Another great article on work flow.

    Version control indeed changed the way I work with most of what I do.

    It is one of the reason I feel in love with text based instructions may it be for LaTeX, Lilypond and Linux and its configurations files. All you need is a good text editor and you are good to go. I also get a sense of why files like .doc files are somewhat disadvantaged.

  3. Pingback: Distributed Editing, Responsibility and Quality | Scores of Beauty

  4. Pingback: Working With Word | Scores of Beauty

Leave a Reply

Your email address will not be published. Required fields are marked *