Introduction to Version Control

Introduction to Version Control#

Course Description#

Version control systems are an incredibly valuable tool for organising software development. They are essential for producing reproducible and transparent research software, coming into their own for facilitating collaborative work. This course will give an introduction to Git, one of the most widely used version control systems in academia and industry. It will also give an introduction to internet platforms such as GitHub and GitLab, which are built on top of Git and designed to facilitate collaboration between software developers and the sharing of code. A key component of the course will be hands-on practice using Git and GitHub, working through theoretical concepts that will be explained with the aid of live demonstrations. By the end of the course, it is intended participants will be comfortable using the basic features of Git and GitHub to keep a record of their day-to-day code development and share their work with others.

Course Objectives#

Use Git to manage their software development.
Explain what repositories and commits are in Git.
Apply standard Git commands as part of their development workflow: cloning, pulling from and pushing to repositories; adding and committing file changes.
Give examples of what should and should not be included in Git repositories.
Describe how Git and platforms like GitHub and GitLab relate to each other and their differences.
Understand how to share their work with others and/or make it publicly available through GitHub.
Have the confidence to learn more advanced features of Git and GitHub as required for their work, such as working with branches and pull requests.

Pre-requisites#

Familiarity of working at a Unix command line (e.g. Apple Terminal, a terminal running Bash) is helpful but not essential. A good introduction to this topic more generally can be found at the sister course - Introduction to Unix.

Version control systems are primarily used for source code development, so experience writing some code (e.g. R, Python, LaTeX, bash scripts, C,…) is helpful, though not essential.

Installation Guide#

All CfRR courses require attendees to use their own computer/laptop to follow workshop activities and take effective notes.

In order to fully participate in this course, you should make sure you have the following in place before the first workshop, with each step described below.

An installation of Git on your computer.
A GitHub account.
A text editor or integrated development environment (IDE) to use for working with source code / text files. Visual Studio Code is recommended as it will be used during the workshop sessions, but you can use another program if you prefer; see the discussion below for more information.

This page gives more details on these requirements.

Please note that installing software, such as Git or a text editor, may require administrative privileges. If you need support due to not having these privileges on your computer then please contact the University’s IT department.

Installing Git#

You should first check whether you have Git installed on your computer, according to your operating system:

Windows: Search for the application Git Bash on your computer. (You can open up a new search by pressing the Windows and S keys together.) If you find Git Bash as an application, then you already have Git installed.
MacOS & Linux: Open a terminal and run the command git --version. If you get a response that looks something like
```
git version 2.25.1
```
then you have Git installed (your version number may differ). On the other hand, if you get a response that says something like
```
Command 'git' not found
```
then Git is not installed.

If you don’t have Git installed then you will need to install it. Instructions and recommended sources for doing this are provided below, according to operating systems.

Windows#

Download and install the latest version of Git for Windows from https://git-scm.com/download/win. Accept the default settings while running the installer, with the following optional exceptions:

On the Select Components pane, you may wish to select the option to Check daily for Git for Windows updates. Selecting this will mean Git for Windows will tell you when a new update for it is available.
On the Choosing the default editor used by Git pane, you can select a different text editor that will be used to write ‘commit messages’ in Git. The default text editor, Vim, is difficult to use if you’re not used to it. Nano is a much simpler text editor that works from the command line, so our recommendation would be to switch to that. The choice of text editor can be changed later once Git is installed, so you’re not tied in by your choice here.

Mac OS#

We recommend installing Git through the Xcode Command Line Tools. This is a collection of software, curated by Apple, that is useful for developing code on MacOS; Git is one of the programs included. Daniel Kehoe has a very good guide on the Xcode Command Line Tools. Daniel’s guide recommends installing the Homebrew package manager at the same time as the Xcode Command Line Tools, however this is not required for installing Git, so we instead recommend following the version of his instructions that avoids installing Homebrew.

Linux#

Install Git using your operating system’s package manager. See https://git-scm.com/download/linux for instructions.

Get a GitHub account#

To set up an account, go to https://github.com/ and click on Sign Up in the top right-hand corner. Make sure you know your username and password for the start of the course!

Text editors / IDEs#

You should also have a text editor or integrated development environment (IDE) installed on your computer, to give you a means of editing text files and source code. Throughout this course we will be using Visual Studio Code (a.k.a. VS Code) because it has nice integration with Git (it’s also free and works on most operating systems). One or two parts of the course will use features in VS Code to better visualise what is going on with Git (such as visualising differences between file versions), so you will likely find it simplest to use VS Code to follow along in this course.

However, if you don’t want to use VS Code then you can use whatever text editor / IDE you feel comfortable with. Examples include:

Notepad++
Sublime Text
Emacs
RStudio (includes Git integration)
PyCharm (includes Git integration)
(At the command line) Vim, Nano

You may wish to see if your preferred text editor / IDE has integrations with Git, or if there are plugins or other extensions that add capabilities for working with Git from within your text editor / IDE.

Installing VS Code#

Head to https://code.visualstudio.com to download and install VS Code for your operating system. Windows users can also install it from the Microsoft Store.

Self Study Material Link#

The self-study material for this course is available here.

Acknowledgements#

This course has been adapted from Software Carpentry’s Version Control with Git course [1] (retrieved from https://swcarpentry.github.io/git-novice/ and http://erdavenport.github.io/git-lessons/10-branching.html), which is © Software Carpentry and licensed under Creative Commons BY 4.0. Changes have been made from the original content.

References#

[1] Ivan Gonzalez; Daisie Huang; Nima Hejazi; Katherine Koziar; Madicken Munk (eds): “Software Carpentry: Version Control with Git.” Version 2019.06.1, July 2019, https://github.com/swcarpentry/git-novice, 10.5281/zenodo.3264950

Developers#

This workshop was developed by Dr Thomas Hawes with the help of Dr Fliss Guest, Dr Matt Johns and Dr Ed Hone.

License Info#

Instructional Material

The instructional material in this course is copyright © 2024 University of Exeter and is made available under the Creative Commons Attribution 4.0 International licence (https://creativecommons.org/licenses/by/4.0/). Instructional material consists of material that is contained within the “individual_modules/introduction_to_version_control” folders in this repository, with the exception of code snippets and example programs found in files within these folders. Such code snippets and example programs are considered software for the purposes of this licence.

Software

Except where otherwise noted, software provided in this repository is made available under the MIT licence (https://opensource.org/licenses/MIT).

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

The software in this repository is adapted from software that is covered by the following copyright and permission notice:

Copyright © 2024 Software Carpentry

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.