Syllabus

Hao Ye Reproducibility Librarian, University of Florida (updated: 2022-07-19)

Intro

🚀 You’ve got a team and a project idea and are ready to GO! 🚀 How do you work together effectively?? * Can you edit files from someone else? * Can multiple people update the project at the same time? * How do you backup everyone’s work? * How do people outside of the project make contributions? * What is in this talk? We will go over basic concepts and workflow practices. - you can get started (even if you haven’t used git or github before) We will conclude with a short hands-on exercise using the GitHub website. This lesson teaches you to: * articulate the differences between git and Github * understand essential features of working in git and github - commits as project snapshots - branches as ways to experiment - remotes and clones - collaboration workflow * create and navigate branches * create and merge pull requests * use the “Github Flow” system * Basic Concepts * Version Control Version Control: tools/systems to manage changes to files ## You are probably already using version control! * MS Word will let you “track changes” * Dropbox / Google Drive store some past versions * Why Learn Git? Git is version control for projects. You can: * restore whole project states (i.e. multiple files at once) * keep track of who made what changes and why * handle changes in any type of file * manage work from large distributed teams * Git and GitHub ## (not the same thing!) * Git * Git is the software and the version control system * default interface is the command line - commands have unintuitive names - error messages can be obscure * many other tools improve on the experience - graphical interface - integration with other things, including GitHub * GitHub * a cloud platform that hosts Git repos * unlimited public and private repos * size limits: - 1 GB for each repo - 100 MB for individual files * GitHub Actions provide continuous integration - great for testing or deploying * Git tracks versions for projects * Basic Mechanics * Versioning occurs on the level of a project: - projects are called a repository (or repo) - a project is a folder and all of its contents (including subfolders) * Changes are recorded by taking a snapshot: - each snapshot is called a commit. * Commit Structure * each commit has a commit message - 1-line summary (required) - blank line - further details * each commit also records who and when * good commit messages help you find the right past project state! * Constructing a Commit * recording commits is done manually - what files have changed since the last commit? add files with changes (including new files) - use commit command
- write the commit message * Why so tedious? - You have control over which changes are recorded in each commit * Navigating Commits * Git generates a unique hash for each commit * You can retrieve a commit by using the checkout command and the desired hash * The file/folder contents will change to reflect the project state for that commit. When working in git, think of files and folders as temporary; changes are not saved unless added to a commit.

GitHub as a Backup System

file backup = store a copy somewhere else How do you backup a Git repository? Git stores all of the information about commits, history, etc. the .git folder of your project * .git is normally hidden * If you copy the project folder, it will also contain the full git history. (i.e. you can back up separately if you want) * You can specify other locations to synchronize a git repository to.
These are called remotes. * GitHub is a cloud remote Setup: 1. Create an empty GitHub repo to be your remote location 2. Synchronize this GitHub repo to your computer Synchronize: 3. push will send all new commits on the current branch to GitHub 4. pull will retrieve new commits from GitHub * Branches Let You Experiment * About Branches For simple projects, your project may progress as a line from beginning to end. If you are solving a new problem, you may want to experiment as you go. branches allow you to label and save work that may or may not end up in a final version to be published. [img: https://www.atlassian.com/git/tutorials/using-branches] * different branches are separate paths, and in different colors * each point on a branch is a commit * Creating new branches (GitHub) * Tips for Creating Branches * choose names that won’t overlap with anyone else’s:
“<name>-<feature>” is a common strategy
e.g. “hao-update-readme” * double check which branch you are in before making a commit! * A Merge/Pull Request Combines Work from Separate Branches * Merges A merge combines changes from separate branches together into a new commit. * If the changes are in separate files or separate sections of a common file, merging is automatic. * Otherwise, a merge conflict occurs, and you need to manually reconcile the differences for the merge commit. * Example Merge Conflict * Pull Requests On Github, start by creating a pull request. Pull requests are a way for a maintainer or a team to review and comment on merges before they happen. * Creating a Pull Request * Collaborating on GitHub * Sharing Repos On GitHub, you can add other accounts as collaborators to give them write access. If you work in the same branch, you have to wait for the other person to finish making changes before you can add yours! * GitHub Flow for Collaborations * a primary branch, e.g. “main”, stores the working version of the project * updates happen in branches * when work is ready to be merged into “main”, create a pull request * after merging, unneeded branches can be deleted * Benefits * work in different areas of the project can happen at the same time, in different branches * subteams can work together on shared branches - pull request from separate branches to a shared group branch - Github enables discussions of pull requests * Exercise We will now test out the GitHub Flow system on your project repos: 1. create a new branch
(named “<your name>-readme”) 2. in GitHub, add your name to the Team section of the README file, and commit the changes 3. create a pull request to the main branch * Takeaway Messages * commits are records of your project * branches are alternate timelines * merges & pull requests combine work across branches * the GitHub Flow system lets you collaborate as a team ## Thanks

• Don’t forget to install the Git software if you want to use Git on your computer.
• I recommend the GitHub Desktop software if you want a graphical client.
• “Understanding the GitHub flow” has more details on the GitHub Flow system