A Tale of Two Projects

Having a history of how a manuscript/project develops is useful. Here is a tale of two projects handled version control.

1.1 Version pit of doom

Does this look familiar?

You are doing version control! There is value of tracking changes to a project and having a history of previous versions.

1.2 Git + GitHub

Below is an example of a version control solution using Git and GitHub.

Figure 1: The most recent version can be found at the GitHub repository page. Importantly we also have access to all previous saved versions of this git project, see Figure 2.

Figure 2: Click the higlighted button to see all saved versions or commits of this git project, see Figure 3 .

Figure 3: This page shows the projects history. We can see not only what progress occured each individual saved step but also navigate to the state of the project at those individual steps, see Figure 4.

Figure 4: Click the higlighted button to see the version of the project at the first save point/commit, see Figure 5.

Figure 5: This is the first version of the project, as you can see it is empty. However as we shown in Figure 3 we have access to the project state at every save point; this makes it easy to reset to a previous point if anything goes wrong.

1.3 Takeaway

Important

This approach of using a version control system (VCS) (Blischak, Davenport, and Wilson 2016) is an industry and academic (Ram 2013) best practice. It is much more ergonomic and reliable than manualy tracking versions.

References

Blischak, John D., Emily R. Davenport, and Greg Wilson. 2016. “A Quick Introduction to Version Control with Git and GitHub.” Edited by Francis Ouellette. PLOS Computational Biology 12 (1): e1004668. https://doi.org/10.1371/journal.pcbi.1004668.

Ram, Karthik. 2013. “Git Can Facilitate Greater Reproducibility and Increased Transparency in Science.” Source Code for Biology and Medicine 8 (1). https://doi.org/10.1186/1751-0473-8-7.