A Friendly Introduction to Github for Project Version Control

# A Friendly Introduction to Github for Project Version Control
### Natya Hans, Informatics and Reproducibility Librarian
### Academic Research Consulting and Services, University of Florida
### (updated: 2023-12-07)

---

# Motivations

Effective project management can *save time*, by making it easy to:
* revert back to previous versions
* collaborate together on the same files
* share your work and have it cited

---

# Learning Outcomes

By the end of the workshop, participants will be able to:

* explain the benefits of version control
* articulate the differences between `git` and `Github`
* create and update repositories using Github Desktop and the Github website
* write descriptive README files
* select and apply a license to a GitHub project

---

# Version Control Concepts

---

# Version Control

Tools/systems to manage changes to files.

--
## You are probably already using version control!

* MS Word has "track changes"
* Dropbox / Google Drive / OneDrive can restore previous versions

---

# What's special about GitHub?

GitHub is version control for **projects**.

Use cases:
* changes that are not in MS Word files
* find a specific version of the project
* identify *who* made changes and  *why*
* collaborate on the same files at the same time
---

# Example scenarios

* You change a histogram to a bar plot, and then you want to change it back.
* Your co-author makes edits while traveling, and you need to combine their changes with changes you made in the meantime.
* You want to experiment with a different dataset / analysis / narrative without duplicating everything.

**GitHub helps you do all of these!**

---

# Git and GitHub
--

## (not the same thing!)

---

# Git

* `Git` is the name of the software and version control system
* notoriously unfriendly
  - commands have unintuitive names
  - error messages are obscure

---

**This workshop does NOT teach you to use Git directly!**
* check out the [resources page](https://uf-repro.github.io/friendly-github-intro/resources.html) for tutorials, guides, etc.

We will learn essential terms and concepts. We will interact with Git through the [GitHub website](https://github.com/) and the [GitHub Desktop software](https://desktop.github.com/).

---

# Git Concepts

* In Git, a project corresponds to a computer folder
  - the folder is called a *repository* or *repo*
  - Git tracks changes to all files and subfolders in that folder
* Changes are recorded by taking snapshots of the folder contents:
  - each snapshot is called a *commit* and represents a specific project version

---

![A screenshot of the website https://github.com/uf-repro/friendly-github-intro/commits/main, showing the commit log for the repo of *this* lesson. Each commit entry has an associated date and time, the author, and the summary of the commit message.](commits_example.png)

---

# About Commits

* each commit has a *commit message*
  - 1-line summary (required)
  - blank line (optional)
  - further details
* commits also record *who* and *when* (automatically)

---

# Creating Commits

Commits are constructed *manually* - you tell git what to include.
 - `add` files that have changed (including new files)
 - Git only records changes (ignoring unchanged files)
 - one common method is to `add` all files
 
*A commit message is required!*

---
# Why so tedious?

* The commit procedure is more work than a simple button press!
* This procedure gives you control over which changes are recorded in each commit
  - if you make edits in multiple files, you can group the changes into meaningful commits
* The commit message is important to find correct versions later

---

# GitHub

* a cloud platform that hosts Git repos
* can host unlimited # of *public* and *private* repos
* size limits:
  - 1 GB for each repo (recommended for performance reasons)
  - 50 MB for individual files
* [GitHub Education](https://education.github.com/pack) has some benefits
  - one code for a free t-shirt from https://github.myshopify.com/ to be given away to a random attendee

---

# GitHub in a Web Browser

---

# Using GitHub

https://github.com
* create an account / log in
* create a new repo
* add text files (in browser) or upload files
* write a commit message

---

# DEMO

---

# Using Git Clones

---
# About Clones

If you want to backup files, you can make a copy to another location (external drive, cloud storage, etc.).

What about a project folder AND its history?

A **git clone** is not just a copy of the project files, but also its entire history.

---
# Synchronizing Repos

* Git is designed to be decentralized -- repos can exist in multiple locations:
  - *clone* = "make a copy of a Git repo"
  - *push* = "send new commits from here to somewhere else"
  - *pull* = "retrieve new commits from somewhere else to here"

---

# Working with Git clones

* you need the `Git` software
  - [instructions from Software Carpentry](https://carpentries.github.io/workshop-template/#git)
  - [guide to command-line usage](https://swcarpentry.github.io/git-novice/)  
    (too advanced for this workshop)

* [GitHub Desktop](https://desktop.github.com/)
  - graphical interface for Git
  - also syncs your computer with GitHub
  
---

# DEMO

---

# Best Practices for Git Repos

---

# Readme

A `README.md` file in the primary folder shows on the github webpage for the repo. It should include:
  - what the project is about
  - who is working on it
  - who is it for
  - installation/usage instructions
  - citation info

---

# License

A `LICENSE` file in the top directory describes how other people can *use* the work.
* by default, in the US, you have full rights on creative works

Recommended permissive licenses, based on content type:
  - MIT (code)
  - CC-BY (non-code)
  - CC0 (public-domain, data)
  
---

# Adding a license

* when creating a new repo, you have the option of choosing the template for an existing license

* on [github.com](https://github.com), adding a file named `LICENSE` brings up a button:

![An animation of adding a file named `LICENSE` in the github.com interface, and then being able to click on a `Choose a License` button](choose-a-license.gif)

---

# Markdown

* GitHub will render some common file formats directly in the web browser:
  - images, plain text
* markdown is preferred for formatting text and images
  - uses plain text, but renders nicely
  - [a guide to syntax](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)

---

[example report](https://github.com/weecology/MATSSdemo/blob/master/analysis/report.md)

![A screenshot of the website https://github.com/weecology/MATSSdemo/blob/master/analysis/report.md, showing a markdown report with formatted text and embedded figures.](markdown_example.png)

---

# Thanks

* Original slides created by Hao Ye, modified by Natya Hans
* Let me know what content you'd like to see
* Contact me for additional questions or consultation requests!
* Check back in on the libguide for more modules and contact info:
  - https://guides.uflib.ufl.edu/reproducibility