Syllabus

Natya Hans, Informatics and Reproducibility Librarian Academic Research Consulting and Services, University of Florida (updated: 2023-12-07)

Intro

  • 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 for tutorials, guides, etc. We will learn essential terms and concepts. We will interact with Git through the GitHub website and the GitHub Desktop software.
  • 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.
  • About Commits
    • each commit has a commit message
      • 1-line summary (required)
      • blank line (optional)
      • further details
    • commits also record who and when (automatically) 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.
  • 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 has some benefits
  • 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
  • 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, 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
  • Markdown
    • GitHub will render some common file formats directly in the web browser:
      • images, plain text
    • markdown is preferred for formatting text and images

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: