John Blischak Make each sentence one line in introduction so that it is easier to track changes.  about 9 years ago

Commit id: f0be56de5e1598ba957d352bbdd0d82f380e432c

deletions | additions      

       

\subsection{Introduction to version control}  A few key problems arise when writing large amounts of code. First, you often need to experiment with new ideas, such as adding new features or increasing the speed of a bottleneck, but you don't want to risk breaking the currently working code. The simplest solution is to copy the script before making new edits. However, this can quickly become a problem because it clutters your filesystem with uniformative filenames, e.g. \verb|analysis.sh|, \verb|analysis_02.sh|, \verb|analysis_03.sh|, etc. It is difficult to remember the differences between the versions of the code, and more importantly which version you used to produce specific results, especially if you return to the code months later. Second, you will likely need to incorporate changes from collaborators. If you email the code to multiple collaborators, you will have to manually incorporate all the changes each of them sends. Fortunately, software engineers have already developed software to manage these issues: version control. Version control software allows you to track the iterative changes you make to your code. Thus you can experiment with new ideas but always have the option to revert to a specific past version of the code. Furthermore, you can record messages as you save each successive version so that you (or anyone else) reviewing the development history of the code is able to understand the rationale for the given edits. Also, it facilitates collaboration. Using version control software, your collaborators can make and save changes to the code, and you can automatically incorporate these changes to the main code base. And the collaborative aspect is enhanced with the emergence of websites that host version controlled code. In this quick guide, we introduce you to one version control system (VCS), Git (\href{http://git-scm.com/}{git-scm.com}), and one online hosting site, GitHub (\href{https://github.com}{github.com}), both of which are currently popular among scientists and programmers in general. But more importantly, we hope to convince you that although adopting all the functionality of a given VCS has a steep learning curve, you can already achieve great benefits by getting started using a few simple commands. Furthermore, not only does using a VCS solve many common problems when writing code, it can also improve the scientific process. By tracking your code development with a VCS and hosting it online, you are performing science that is more transparent, reproducible, and open to collaboration \cite{23448176}. And there is no reason this framework needs to be limited only to code; a VCS is well-suited for tracking any plain-text files: manuscripts, electronic lab notebooks, protocols, etc.