An introduction to GitHub for chemists

• Date: 24th October 2017, 3 - 4pm
• Location: Unilever Lecture Theatre, Department of Chemistry, University of Cambridge, UK
• Sign up here
• Please bring your laptop or mobile device if you'd like to follow the practical part
• WiFi connection:
  • ChemNet (chemistry members)
  • eduroam
• Refreshments provided

Overview

Are you interested in learning Git and GitHub to manage your code, manuscripts or research data? This introductory workshop will be covering the following:

• Background and motivation
• What is Git? What is version control? What is GitHub?
• How can Git and GitHub be useful for you?
• Practical session: working with Git and GitHub

Background and motivation

• A system to keep track and compare the history of changes made to your files (versions)

• A platform to share and showcase your work online with colleagues and beyond

• Team work often means unnecessary work for some:

  • Many people working on the same file at the same time (you, your lab colleague, your group leader, collaborators abroad ...).
  • Multiple versions of it (e.g. research manuscript, computer script ...).

(http://phdcomics.com/comics/archive_print.php?comicid=1531)

What is Git? What is version control? What is GitHub?

Git is a free and open source distributed version control system, which allows you to:

• Create repositories to host your projects using the command-line.
• Track changes in the files and folders within your repositories.

Version control systems were originally created by groups writing software and code (e.g. Linux project), but can be used for any kind of files or projects.

(adapted from http://lhzuigao.com/309note.html)

Advantages of distributed over centralised version control systems involve:

• If the central repository (server) crashes, it could be recovered / backed up from any of the local repositories created by the researcher, collaborator or group leader.
• Each person can make changes to their local repositories offline. Then integrate their individual changes in the central repository (server) when connected online.

GitHub is a web platform that allows you to upload and manage your local or central repositories online (Hub). It provides:

• A backup of your repositories
• A nice visual interface to your repositories
• A way to collaborate with others

Changes are identified by a revision number, e.g. 60363b1. Each revision is associated with a timestamp and the person making the change. Revisions can be compared, restored, and with some types of files, merged.

There are other softwares for version control, e.g. subversion (svn).

Interfaces to Git and GitHub

• Via the command-line using git

• Directly online

• Github Desktop (available for Mac and Windows)

(https://programminghistorian.org/lessons/getting-started-with-github-desktop)

For this workshop, we are mainly using GitHub's online interface, but also some command-line.

Public (free) and private repositories

A user has to create a GitHub account in order to create repositories:

• Public repositories are free, and can be browsed and downloaded by anyone.
• Private repositories have associated costs - see pricing of plans. The developer plan costs $7/month but it is free if you are a student / academic.

There are alternatives to GitHub, e.g. GitLab, which works similarly but uses a different strategy with free private repositories and cost plans for public ones. Other alternatives: Bitbucket.

Markdown

GitHub uses Markdown, a language with plain text formatting syntax, to render pages online. See examples of Markdown syntax here.

How can Git and GitHub be useful for you?

Some examples

These are many ways how people use Git and GitHub.

• To host and share your research outputs, software or training materials

  • Research slides by Bérénice Batut.
  • The Balasubramanian laboratory computational projects.
  • The Bender group GitHub page.
  • The source code of the BWA software, which aligns DNA sequences to reference genomes, is available here.
  • The source code of the PIDGIN software, which predicts protein targets for drug-like molecules, is available here.

• To create websites

  • Using GitHub pages to create your personal research website.
  • To distribute information about your courses and activities, e.g. the Statistics course in the University of British Columbia is hosted here.

• To share the contents of a book

  • The Bioinformatics Data Skills book shares materials in a dedicated GitHub page.

In the context of our research group

• Most projects have both an experimental and a computational leader

• Classical ways of sharing are: conversations/meetings, email, DropBox, common/shared folders ...

• An environment where:

  • Computational colleagues can share code and results, review work of others and get credit from their collaborative project work.
  • Experimental colleagues can follow development, access computational results and learn methods of data analysis.

• Reproducibility in computational research to avoid situations like ...

(http://phdcomics.com/comics.php?f=1689)

• A happier lifetime for a project:

(https://github.com/semacu/talks/tree/master/20170703_GitHubintheLab_CRUK-CI)

Practical: working with Git and GitHub

We have four possible tutorials:

• Create a GitHub account (+)
• Create your first repository (+)
• Explore your first repository and GitHub account (++)
• Making changes using Git in the command-line (+++)

Create a GitHub account

• Go to https://github.com
• Fill in your Username, Email and Password. Then click on the green button "Sign up for GitHub".

• Choose your personal plan page. For now select "Unlimited public repositories for free". Then click on "Continue".

• Tailor your experience page. Choose the boxes that apply to you and click on "Submit". Otherwise, just go to "skip this step".

• You have created a GitHub account! 😄

Create your first repository

• If you are not already signed in, sign in to GitHub using the Username/Email and Password created before.
• Click on the top-right "avatar" icon and select "Your profile". Have a quick browse through your page.

• Click on the top-right "+" icon and select "New repository". Verify your email address. You should have just received an email from GitHub in the address provided above. Find this email and click on "Verify email address".

• Create a new repository page. Fill in a "Repository name", e.g. my_first_repository or my_analysis_script. For now choose "Public" and select the box to initialize this repository with a README. Finally, click on "Create repository".

• You created your first repository! 🚀

Explore your first repository and GitHub account

Your first repository

• Click on README.md and go to the middle-right pencil "Edit this file". Type anything to change the file, e.g. "GitHub is fun!".

• Scroll down. Introduce a commit change message, e.g. "My first update", and select the radio button "Commit directly to the master branch". Then click on "Commit changes". Voilá!

• To view your history of commits for README.md, click on README.md and go to the middle-right "History" button.
• Alternatively, to view your history of commits for your first repository, click on the name of your repository and select the tab depicting a small clock and the number of commits next to it.

Bonus points:

• Try to create a new file
• In your new repository, have a look at the "Settings" tab, explore "Collaborators" and try to add the person sitting next to you.

Your GitHub account

• Click on your top-right "avatar" icon and select "Settings".

• Explore the tabs "Profile", "Account" and "Emails".

Making changes using Git in the command-line

Check if Git is already installed in your computer, otherwise install Git

• (If in Mac), go to Finder -> Applications -> Utilities -> Terminal and type git --version.

  • If you get as output something like git version 2.5.4 (Apple Git-61), then Git is already installed -> Jump to the next section.
  • If you get something around git: command not found, keep reading.

• To install Git in Mac, follow one of the next strategies:

  1. When running one of the following commands git --version, git config or xcode-select --install you may be offered to install developer command line tools. Accept the offer and follow with "Install".
  2. Go to https://git-scm.com/downloads and download git. Double click on the downloaded executable and follow instructions.
  3. If you have homebrew installed, type the following in the Terminal: brew install git.

• Check the following for installing in Windows or Linux.

Tell git who you are (your GitHub username) and what your email address is

Example:

cd ~/Desktop
git config --global user.name "githubchemistry"
git config --global user.email "[email protected]"

Check:

git config --list

Clone the repository created before

git clone https://github.com/githubchemistry/my_first_repository.git
cd my_first_repository
ls -lh
#-rw-r--r--  1 martin03  1310    38B 24 Oct 09:16 README.md

Your first repository created using GitHub is now a local repository located in your Desktop folder.

Tell git what's your repository url to pull and push commits

cd ~/Desktop/my_first_repository
git remote set-url origin https://[email protected]/githubchemistry/my_first_repository.git

Check:

git remote -v

Make a change to the README.md file using your favourite text editor

• In your Desktop, go the cloned folder and open README.md with a text editor, e.g. TextEdit.
• Change the file, e.g. add a new line "This is my second line of script" and save changes.
• Check how changes are tracked by Git:

cd ~/Desktop/my_first_repository
git status

Now the status of README.md is modified.

Stage and commit the change

Staging:

git add README.md
git status

Committing:

git commit -a -m "My second update"
git status

Push changes to your online GitHub repository

git push origin master

Now check that your change to README.md made to your online GitHub repository.

Bonus points:

• Make another change to README.md using the online GitHub repository and pull the change to your local repository (Hint: git pull).

Done!

Thanks for your attention! Enjoy GitHub!

Feedback? Any other questions about the workshop/GitHub? Just email: [email protected]

Feedback

Many thanks for the responses. Comments available here.

Additional reference materials

Blogs:

• Beyond Basic R - Version Control with Git

Books:

• Happy Git and GitHub for the useR

Courses:

• GitHub On Demand Training
• Software Carpentry workshops
• A Friendly Introduction to GitHub
• A quick introduction to Git and GitHub
• Version Control with Git
• Git Intro for Librarians

Help:

• GitHub Help

Papers:

• Perez-Riverol et al. Ten Simple Rules for Taking Advantage of Git and GitHub

Videos:

• GitHub Training & Guides
• Git & GitHub tutorial for Beginners

Websites:

• git
• Mastering Markdown

License

This work is distributed under a CC-BY license. Anyone may copy, distribute, display and perform the work and make derivative works and remixes based on it only if they give the author attribution.

Acknowledgements

Clair Castle for the organisation and Nathan Pitt for filming. Our sponsors: