Version control with Git and GitHub

Version control software such as Git is used for:

  • tracking changes to a set of related (mainly) text files (which could be code, configuration files, simulation definitions, workflow definitions, web pages and/or journal paper drafts)

  • logging who made changes, when and why.

  • providing mechanisms for collaborating with others on text files, which is most commonly done using a cloud-based host of Git repositories e.g. GitHub.

An understanding of how to use Git and of the problems it attempts to solve is increasingly valuable.

Getting started with Git

  • Will Furnass gave a presentation to Insigneo researchers on the basics of Git in July 2018. The slides can be viewed online.

  • Those slides include recommendations for software that allows you to use Git.

  • The Git Immerson tutorial provides a concise introduction to using Git from the command-line.

Getting started with GitHub

  • Register for a GitHub account. By default you will only be able to create public repositories.

  • Through the GitHub Education for Researchers programme you can request for a free upgrade to your account that allows you to create an unlimited number of private repositories. This requires that you either

    • Registered for a GitHub account using your University of Sheffield email address _or_

    • Associate your University of Sheffield email address with your existing GitHub account (as a secondary email address)

  • You may then want to ask to be added to the Insigneo GitHub organisation.

Insigneo GitHub organisation

There is an ‘Insigneo’ Organisation on Github, https://github.com/INSIGNEO/, associated with which are various public and private repositories. Associated with this Organisation account is a coupon that entitles Insigneo to ‘100% off forever’. Conditions of use:

The coupon applied to [Insigneo’s] account is reserved for organizations that are using GitHub in their research ventures. [GitHub does] not encourage commercial use of an Organization with the coupon active on the account. [GitHub recommends] creating a separate Organization for any commercial use.

More information on the differences between personal user accounts and organisation accounts.

If you want to give your work Insigneo branding then it is recommended that you create repositories within this organisation rather than within your personal GitHub account.

To request that you be made a member of the Insigneo Github Organisation please contact the Insigneo tech team.

Sensitive information

Be warned that once sensitive information has been committed to a Git repository it can be difficult to remove it. You should think carefully before committing any of the following to a repository:

  • Names, email addresses, person IDs or any other sensitive information;

  • Code or other resources that you may not have permission to distribute.

If in doubt as to what is appropriate, please contact the Insigneo tech team.

Public repositories and licensing

Before making any repository public you first need to discuss the license under which the repository’s contents are to be made available. This needs to be discussed with the relevant PI and possibly the funder too. The Insigneo tech team can also contribute to this discussion.

Hands-on training

May be provided in future.