Summary and Schedule

This lesson will help USGS researchers and software developers learn how to do the following:

  • Create a Git repository for tracking version-controlled software.
  • Collaborate with others using USGS GitLab.
  • Create a USGS-compliant scientific software information product with source code, metadata, disclaimers, license, and citation.
  • Publish a scientific software information product.

Lesson Narrative

Dracula is a researcher at the U.S. Geological Survey. He is working with Wolfman, a researcher at Euphoric State University on a project to model the co-occurrences of vampires and werewolves on Mars. They want to be able to work on the code at the same time, but they have run into problems doing this in the past. If they take turns, each one will spend a lot of time waiting for the other to finish, but if they work on their own copies and email changes back and forth things will be lost, overwritten, or duplicated.

A colleague suggests using version control to manage their work. Version control is better than mailing files back and forth:

  • Nothing that is committed to version control is ever lost, unless you work really, really hard at losing it. Since all old versions of files are saved, it is always possible to go back in time to see exactly who wrote what on a particular day, or what version of a program was used to generate a particular set of results.

  • As we have this record of who made what changes when, we know who to ask if we have questions later on, and, if needed, revert to a previous version, much like the “undo” feature in an editor.

  • When several people collaborate in the same project, it is possible to accidentally overlook or overwrite someone’s changes. The version control system automatically notifies users whenever there is a conflict between one person’s work and another’s.

Teams are not the only ones to benefit from version control: lone researchers can benefit immensely. Keeping a record of what was changed, when, and why is extremely useful for all researchers if they ever need to come back to the project later on (e.g., a year later, when memory has faded).

Version control is the lab notebook of the digital world: it is what professionals use to keep track of what they have done and to collaborate with other people. Every large software development project relies on it, and most programmers use it for their small jobs as well. And it is not just for software: books, papers, small data sets, and anything that changes over time or needs to be shared can and should be stored in a version control system.

Prerequisites

In this lesson we use Git from the Unix Shell. Some previous experience with the shell is expected, but is not mandatory.

The actual schedule may vary slightly depending on the topics and exercises chosen by the instructor.

Installing Git

Details

This lesson will use Git and Bash.

Git is a version control system that allows you track who made changes to what, and when those changes were made. Git also has options for easily updating a shared or public version of your code on GitLab.

Bash is a commonly-used shell that gives you the power to do tasks more quickly.

Follow the instructions below to ensure you have the proper software installed on your computer.

GitLab Account

By default, all USGS personnel with Active Directory credentials will have a GitLab account automatically provisioned for them upon their first access of https://code.usgs.gov. Go to https://code.usgs.gov, click the “Sign In” button in the top-right, and use the “USGS Login” button.

Preparing Your Working Directory

We will do our work in the Desktop folder so make sure you change your working directory to it with:

BASH 

$ cd
$ cd Desktop

If your Desktop is backed up by OneDrive, change your working directory to it with:

BASH 

$ cd OneDrive\ -\ DOI/Desktop

Note: You can start typing OneDrive and then hit Tab to autocomplete through “DOI/”. Then, starting typing Desktop and hit Tab to autocomplete.