/ versioning

Binary Files And VCS

I've already written about why you should not add binary files to your code repository but, there are some cases where it seems you cannot do otherwise.


The main exception to the general rule is for images and other files that are part of the final output. If you think about a complex website, it can happen that the most part of the files in your repository are not texts.

There can be images, PDFs, compressed archives, etc. There's not much to say about those files: you have to include them in their binary formats. Even if it is theoretically possible to generate some of them starting from an original text file, usually it isn't worth the trouble.

Code Documentation

The various offices suites are able to generate wonderful documents but, unfortunately in binary format. Good alternatives are Markdown and Sphinx. You write in plain text with minimum markup characters and quickly you can generate HTML documents. Adding your own CSS is a trivial operation that lets you customize the output.

Of course, technical documentation needs graphics too. But in this case you can think about this great text-to-png converter.

Docs generated with the above tools can be added to (or integrated with) the output of Doxygen that transforms the comments in your code into a searchable website.

Bottom Line

Just like in many other fields, words like "always" and "never" are not applicable. When in doubt, carefully evaluate pros and cons, considering that your VCS cannot help you much with binary files.

Image by Scott Norris taken from Flickr licensed under the Creative Commons Attribution-NonCommercial-NoDerivs 2.0 Generic license.