class: center, middle, inverse, title-slide # A Crash Course on Git & GitHub ### <p>Maria Kamenetsky <br /> (she/hers)</p> ### <p>PhD Candidate, Epidemiology <br /> University of Wisconsin-Madison</p> ### April 7th, 2021 --- # Overview - Introductions - Git/GitHub Motivation - Set-Up - Example Workflows: - Individual projects - Working on teams - Acknowledgments and Resources --- # Assumptions - Some knowledge of Git and GitHub already - Some knowledge of using the command line - You have a terminal that you use and it works (ex: xterm, cygwin, Git Bash) - You have a GitHub account already and Git is installed and working on your computer --- # Introductions - Say "hello" and introduce yourself. - Please share your: - Name and short description of your research/work. --- # What Does Git Do? - Keeps track of changes made to files - Lets you go back to old versions - Allows you to only have one version in your directory - Collaborate with others - Publish your code/data (GitHub) .center[] --- # Git vs. GitHub **Git** - Software that is installed locally on your computer system - Primarily a command line tool - Purpose is to manage the versioning of files in the Git repository - Open source license - Competes with Mercurial, Subversion, IBM, ClearCase ---- **GitHub** - A cloud-hosted service - Provides a graphical interface - Allows user to upload a copy of a Git repository - Purchased by Microsoft in 2018, but has free tiers - Competes with Atlassian, BitBucket, and GitLab --- #The Terminal - MacOS users should have a terminal (sometimes called xterm) - Linux users should be very familiar with the terminal already - Windows users: use whichever terminal you are currently using. If you don't use a terminal, please download [Git Bash](https://gitforwindows.org/). --- #Set-Up In your terminal, if you haven't yet configured Git on your computer please do so. If you are already up and running, then skip this step: ``` # Initial configuration steps for Git git config --global user.name “[your name]” git config --global user.email “[your email address]” git config --global color.ui “auto” git config --global core.editor “nano -w” ``` - use the same email address that you use for your GitHub account - if you make a typo, don't worry - just re-run the command - these settings are global, not for a particular folder --- #Making Your Own Git Repository - Navigate to your Desktop in your terminal - In practice, this will be wherever you want to keep your project folder ``` cd ~/Desktop/ ``` - We're going to create a new project directory called `planets` and initialize it as a Git repository ``` mkdir planets # make the directory cd planets # change directory into planets git init # initialize Git repo ls -a # you should see a hidden .git folder git checkout -b main # create main as the main branch git status ``` .center[] --- #Making Your Own Git Repository - You should not initialize a Git repository inside another Git repository - it's redundant and things get weird. - If this happens or you want to get rid of Git version control of a project, just delete the `.git` hidden folder with `rmdir .git` *Pro-tip:* To view all hidden files in a folder, use `ls -la` --- #Adding Files to Your Git Repository Now that the Git repository is initialized, let's add files: ``` nano mars.txt # nano is the editor, mars.txt is the file I'm creating ``` "Cold and dry, red is my favorite color" <- add this to `mars.txt` - CTRL+o (to save in nano) - CTRL+x (to exit nano) ``` git status ``` .center[] You should see that you have untracked changes in `mars.txt` --- #Adding Files to Your Git Repository ``` git add mars.txt # we want Git to track this file git status ``` .center[] --- #Committing Your Changes ``` git commit -m "started notes on Mars as a base" git status ``` .center[] Let's say you make several changes to this repository, and have several commits. These commits are all local to your computer, but you want to keep them on GitHub (*remote*) as a back-up. --- #Connecting to GitHub (*remote*) 1. Go to GitHub and create *New repository* (call it *planets* for our example) 2. At the top of the GitHub repository you just created, copy the remote repository url - Example: `https://github.com/mkamenet3/planets.git` 2 Ways to link to GitHub: **1) Link Existing Local Repository to GitHub** ``` git remote add origin https://github.com/mkamenet3/planets.git # use your url here instead of mine git remote -v ``` .center[] --- #Connecting to GitHub (*remote*) **2) Create GitHub Repository and clone it locally** ``` git clone https://github.com/mkamenet3/planets.git ``` *Pro-tip:* GitHub walks you through all of these instructions! .center[] --- #Push Your Changes to GitHub (*remote*) Now that you've connected your repository to your GitHub, it's time to push your changes: ``` git push origin main ``` (You will be prompted for your username and password) Go to GitHub and see your changes there! .center[] --- #Best Practices to Use Git with GitHub - Git and GitHub used together are not tools, but workflows - Depending on if you work by yourself or in teams, your workflow can look different. .center[] --- #Best Practices to Use Git with GitHub **Branches** - Instead of always working on your `main` branch, it's a good idea to keep that as the last clean working version - To test out new code, add new features, any intermediate changes that are in progress, use branches - You already have one branch called `main`, you can make branches off of `main` (or any branch) and use those to work through your intermediate code. - Once you have made your final edits, you can merge those branches into `main` using a **Pull Request** .center[] --- #Add Branch `addstars` ``` git branch # check to see the names of your current branches git branch addstars # create new branch git checkout addstars # switch to the addstars branch git branch # check you are on branch addstars ``` - *Pro-tip*: You can create a new branch and move to it in one command: `git checkout -b addstars` Modify `mars.txt` by adding: "The North Star is also known as Polaris, how cool!" Use `git diff` to see the differences between the previously committed version of `mars.txt` and the new changes you just made: ``` git diff mars.txt ``` .center[] --- #Commit Your New Changes on `addstars` branch ``` git status git add mars.txt git commit -m "added new info on Polaris" git push origin addstars ``` .center[] --- #Create a Pull Request to Merge `addstars` branch into `main` .center[] If you just pushed changes to GitHub, the *Compare & pull request* button will appear. If you want to merge an older branch, go to *Pull requests* and manually select which branches to merge (in this case, you want to merge `addstars` to `main`). --- #Create a Pull Request to Merge `addstars` branch into `main` .center[] Here you can add additional comments about the changes you are proposing and ping people to review your code. --- #Merge `addstars` branch into `main` .center[] --- #Merge `addstars` branch into `main` .center[] - It's good practice to delete the branch once you merge it in or the issue has been completely addressed. --- #Confirm changes appear on `main` branch .center[] - Notice there are no open pull requests anymore - You are on the `main` branch and these changes have been successfully merged in - The last commit message reminds you of what changes you merged into `main` --- #`git pull` updated copy of `main` from GitHub to your local machine ``` git checkout main # switch back to main branch git pull origin main ``` Now your *local* copy of `main` is synced up with the GitHub copy (*remote*) of `main`! If you are happy with these changes go ahead and delete the branch `addstars` locally: ``` git branch -d addstars # delete addstars branch ``` Start the cycle all over again! --- #The Whole Workflow .center[] --- #On a Team **Suggested workflow**: - Add issues - Create branch based on issue .center[] --- #Summary - Git/GitHub used together are a workflow - find a flow that works for you and your tema - Keep the `main` branch as the "safe copy" that you know works. - When you write new code/trying things out, best to create a new branch. - Once you workout the kinks, then merge in your branch onto main on GitHub - On your local machine, switch to `main` (`git checkout main`) and pull from the main branch on GitHub to your local machine (`git pull origin master`) - Now you're ready to create a new branch from `main` and keep working. - If working on a team, remember to pull the latest copy of the `main` branch before starting a new branch --- #Using Git with RStudio - Create a new repository on GitHub - Checkout a project from a version control repository - Under the `Git` tab, click `New Branch` and then `Add Remote...` --- #Useful Git Terminology - `git fetch`: Retrieve latest metadata from origin, but don't transfer any files (check to see if there's anything new). - `git pull`: Check to see if there are changes *and* apply them to local repository - `git revert`: Undo changes to a repository's commit history; does not move `HEAD` - `git reset`: Move `HEAD` pointer and current branch pointer - `git rebase`: Moving or combining a sequence of commits to a new base. Instead of merging, change current branch to the new main or base branch; rewrites commit history. An alternative to `merge`. - `git blame`: Annotate each line of a file with information about revisions and who authored them. - **staging area**: You have added files that are tracked, but they are not committed yet. - **upstream**: The original repository you clone from. - **fork**: A copy of a repository (that is upstream) that you manage. - **origin**: Remote repository project was cloned from. - **HEAD**: Represents current snapshot of a branch; the active or current branch. --- # Acknowledgments and Resources **Acknowledgments** - The Carpentries: [*Version Control with Git*](https://uw-madison-datascience.github.io/git-novice-custom/) - Sarah Stevens, Data Science Hub Facilitator, University of Wisconsin-Madison ---- **Resources** - The Carpentries: [*Version Control with Git*](https://uw-madison-datascience.github.io/git-novice-custom/) - The Server Side: [Git vs. GitHub](https://blog.devmountain.com/git-vs-github-whats-the-difference/#:~:text=GitHub%E2%80%A6-,what's%20the%20difference%3F,help%20you%20better%20manage%20them) - Medium: [Git vs. GitHub](https://medium.com/edureka/git-vs-github-67c511d09d3e) - [Adding an Existing Project to GitHub Using the Command Line](https://docs.github.com/en/github/importing-your-projects-to-github/adding-an-existing-project-to-github-using-the-command-line) - [Git Basics-Getting a Git Repository](https://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository) - [Merge Conflicts](https://blog.axosoft.com/learn-git-merge-conflict/#:~:text=A%20merge%20conflict%20is%20an,merge%20commits%20without%20your%20help.) - [Using Git from RStudio](https://uw-madison-datascience.github.io/git-novice-custom/15-supplemental-rstudio/) - [Using Git with RStudio](https://jennybc.github.io/2014-05-12-ubc/ubc-r/session03_git.html) - [Confusing Terms in the Git Terminology](https://levelup.gitconnected.com/confusing-terms-in-the-git-terminology-c7115d6febc7) - [Git Glossary](https://www.git-tower.com/learn/git/glossary/origin/) - [About Forks](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-forks) --- class: center, middle # Thank you! mkamenetsky@wisc.edu @mkamenets https://mariakamenetsky.com/