Snacker News

Use version control for your laboratory protocols

October 16, 2019

Changes to laboratory protocols need to be kept track of. Documenting who made a change and why is important to ensure reproducibility of results. It also empowers people who think of improvements to a protocol to communicate those changes to the other users.

A very bad way to “version control”

I’m sure we’ve all seen file names like Protein production protocol (copy) v2 DAC FINAL_VERSION Lab7 edit 2018-11-11 (revert volume) 2.docx. As funny as they are, file names like this are a cry for help. “How can I keep track of this complex, living document that’s shared by the whole lab?” The answer is probably not by making a really long file name with (sometimes) annotated changes in it.

A better way of versioning: Git

Git is a funny little version control system. You can turn any directory into a Git repository with the command git init .. But what does that get you? You can make as many changes as you like and Git won’t actually keep track of any of the changes, it will just tell you that which files have changed since you typed git init .. So what good is it?

Git asks you to keep track of the changes yourself. The process looks like this after you make your changes. You tell Git to keep track of the changes you made with git add protocol.txt, and then commit your changes with git commit. This pops up a text window (your default editor). Into this text window you type a short message, describing what the change does to the protocol. For example, it might say “Add a third wash step to the column purification”, or “Change concentration of sodium chloride to 200 mM in the wash buffer”. This commit is an extremely concise and information rich description of the change. Git keeps

  1. your name, email address, and the current date and time so it’s easy to tell who updated the protocol, and when
  2. a detailed, word-by-word comparison of the document before you changed it and your updated version
  3. your commit message describing your change
  4. a globally-unique identifier for this version of the protocol (that is human and machine readable)

Pretty cool, right? And it only requires you typing in a description of your changes into a text editor instead of in the file name.

Next-level Git for teams

Teams and other collaborative groups using a shared protocol are in the best position to benefit from version control. Experiments can be associated with the unique identifier of the version of the protocol that is used. People can quickly check for updates to a protocol before running it. Changes are documented so the whole team understands what changed and why.

Hosted Git repositories are a very useful tool for enabling collaboration. Companies like GitHub provide free hosting of Git repositories that include tools for encouraging common workflows, such as a GUI for merge requests that enables discussion to be interleaved with code.