What to keep in source control

You may want to keep in mind two ideas:

  1. The repository should be self-contained or, in other words, enable the experiments contained in it be reproduced.
  2. Do not track files that are generated from other files (e.g. PDFs generated from
    LaTeX, or tex files generated from Markdown).

For the first one: if your repository has a document that contains images, it should contain every source item (image, source code) that enables render (build) the document. Besides keeping track of the changes, think in the source code as a backup. If you lose the images, you cannot to reproduce the same output as before. If you update the images and you do not track them, you cannot reproduce an earlier version of the document. Unless, you include mechanisms to generate the images.

For the second, do not add files that are automatically generated by tools, or that you can generate by running your own script that lives in the repository. What you can do is to add a script to automate the generation of those files (if those involve several steps to make them).

In summary, the question you have to answer yourself: if you retrieve a pristine copy from the repository, can you obtain the output you are expecting?

3 Likes