Manual Version Control

Overview

Teaching: 15 min
Exercises: 0 min

Questions

• What is version control and why should I use it?

Objectives

• Understand the benefits of a systematic version control system.

• Understand what version control tracks.

• Understand what steps are involved.

We’ll start by exploring how version control can be used to keep track of what each person did and when. Even if you aren’t collaborating with other people, version control still leaves you with a record of your changes that future-you will be grateful for. Manual version control can be a laborious process, but is still better than nothing at all. For much more detail on this subject, please see Good Enough Practices in Scientific Computing, Wilson et al, from which this material has been pulled.

• Keep all files related to a project in a single directory
• Within that directory, keep types of files separate. Good subdirectories include:
  • data/ (for data files)
  • scripts/ (for analysis files)
  • results/ (for files generated from your analysis scripts)
  • writing/ (for papers, posters, etc)
• The top project directory should also contain a README.txt file and a CHANGELOG.txt file.

The README.txt file should contain an index of the directory’s contents and a brief description of the project. The CHANGELOG.txt file has a section for each date a change was made to any file, and a bullet point describing, in brief, what the change was and who made it. New copies of each file are generated with each change, with the date in ISO format so they are computer-sortable, and they can be cross-referenced with the change log.

Key Points

• Version control reduces mental clutter.

• Version control allows for easier reversion.

• Version control allows multiple people to work in parallel.