Skip to content

Commit

Permalink
add batch of tutorials
Browse files Browse the repository at this point in the history
  • Loading branch information
@JessicaS11
JessicaS11 committed Jul 29, 2020
1 parent 6c32e7e commit 45fc4cb
Show file tree
Hide file tree
Showing 78 changed files with 79,846 additions and 2 deletions.
44 changes: 44 additions & 0 deletions 03.Git_and_GitHub/README.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
# Introduction to Git and Github

[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/ICESAT-2HackWeek/intro-git/master?urlpath=lab)
[![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://github.com/ICESAT-2HackWeek/intro-git/blob/master/LICENSE)

## A short tutorial for the ICESat-2 2020 Online Hack Week

_Shane Grigsby, Aimee Barciauskas, Sebastian Alvis, Yara Mohajerani, Fernando Paolo, Fernando Pérez, Anthony Arendt, David Shean, Daniel Shapero, Tyler Sutterley, Jessica Scheick_

This tutorial is hosted on the [Github ICESat-2 HackWeek organization](https://github.com/ICESAT-2HackWeek/intro-git).

## Schedule (all times in PDT)

*Date:* June 10.

From 8:45 to 9am, we'll have a pre-tutorial "getting connected" section. Please come to this part to ensure everyone is on the same page and we can all start together at 9am with the main content:

- 9:00-9:10 [Fernando Pérez]: [Overview of our basic tools and setup (slides)](https://docs.google.com/presentation/d/1pOWte7V5UbnVBvRktvLbLTRluDwrGbXtIdAZhzAd1AE/edit?usp=sharing
): Jupyter and Pangeo
- 9:10-9:20 [Fernando Paolo]: Command Line Basics
- 9:20-9:30 [Fernando Pérez]: Git: Introduction and Fundamentals
- 9:30-10:00 [Fernando Pérez]: Git: first tasks
- 10:00-10:25 [Daniel]: HackWeek Github Worfklows
- 10:25-10:40 [Fernando Pérez]: Wrap up

## Setup
1. Login to JupyterHub:
https://icesat-2.hackweek.io
2. Open a Terminal:
Find Terminal icon at the bottom (or click the + sign on the top left)
3. Clone GitHub repo (type on the terminal):
`git clone https://github.com/ICESAT-2HackWeek/intro-git.git`

## Questions

Post your question in the [#questions](https://icesat2hackweek.slack.com/archives/C014V14KA3G) channel on Slack.

## Credit

This collection of tutorials was adapted from the [2019 ICESat-2 Hackweek tutorial](https://github.com/ICESAT-2HackWeek/intro-jupyter-git) by [@fperez](https://github.com/fperez). Materials for 2020 were co-developed by the instructor team above.

## License

All code and content in this repository is free software: you can redistribute it and/or modify it under the terms of the BSD License. A copy of this license is provided in [LICENSE](LICENSE).
330 changes: 330 additions & 0 deletions 03.Git_and_GitHub/collaboration-exercise.ipynb
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,330 @@
{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# GitHub collaboration exercise"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"In this exercise we will use GitHub to experiment with collaborative workflows."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Until now, you have been tracking your own work using Git version control commands. But what if you would like to share these changes within a team, similar to what we will be doing during our hacking sessions? For this, it makes sense for us to have a copy of the repository on a centralized hub, rather than storing it on someone's laptop. There are several different flavors of such \"hubs\", but for our purposes we will use GitHub. "
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Collaboration scenario\n",
"\n",
"Imagine a colleague has created a repository that is now hosted on GitHub. You would like to take this work and make some additions to it. Here is the workflow we will follow:\n",
"\n",
"* We'll create a copy of the repository on our own local laptop. This process is called \"cloning\". \n",
"* We will make some changes to the files\n",
"* Assuming we have permission to do so, we can then upload these changes back to the GitHub repository (this process is called \"pushing\")."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Step 1: Cloning\n",
"\n",
"For this exercise we'll be using a [sample GitHub tutorial repository](https://github.com/ICESAT-2HackWeek/sample-repository). Navigate to this repository and have a look around. We'll imagine this is a colleague's working repository to which we'd like to add some changes."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Clone this repository to your local directory. Start by copying the URL for this Git repository to your clipboard:\n",
"\n",
"![copy git URL to clipboard](images/clone-copy-clipboard.png)\n",
"\n",
"Next, clone this repository to your local directory. Type \"git clone\" and then paste in the URL:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": true
},
"outputs": [],
"source": [
"%%bash\n",
"\n",
"git clone https://github.com/ICESAT-2HackWeek/sample-repository.git"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Step 2: Make some changes!\n",
"\n",
"Now, make some changes! In order for us all to avoid merge conflicts, let's create a new folder in the \"participants\" folder. Give the folder a unique name, for example your first name and last name. \n",
"\n",
"**NOTE**: replace the text in the code block here with your actual name:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": true
},
"outputs": [],
"source": [
"%%bash\n",
"cd sample-repository/participants\n",
"\n",
"mkdir myfirstname-mylastname"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Next, make a new file in the folder you just created:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": true
},
"outputs": [],
"source": [
"%%bash\n",
"cd sample-repository/participants/myfirstname-mylastname\n",
"\n",
"touch \"sample-file.txt\""
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Finally, choose whatever method you'd like to add some arbitrary text to that file."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Step 3: add/commit\n",
"\n",
"After you save changes, we'll follow our usual steps within any Git workflow: we'll ```add``` and ```commit``` the changes we've just made:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": true
},
"outputs": [],
"source": [
"%%bash\n",
"\n",
"git add sample-repository/participants/myfirstname-mylastname/sample-file.txt"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": true
},
"outputs": [],
"source": [
"%%bash\n",
"\n",
"git commit -m \"initial commit\""
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Step 4: upload your changes to GitHub\n",
"\n",
"To 'push' our changes, we have to determine where our changes will be pushed to. When we cloned the repo above, we automatically set the source of the clone as the 'upstream remote'. You can see the specific details in the file `.git/config`:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": true
},
"outputs": [],
"source": [
"!cat .git/config"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Assuming you have write permissions to the repo `[remote \"origin\"]`, pushing is accomplished with:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": true
},
"outputs": [],
"source": [
"%%bash\n",
"\n",
"git push"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The above command will generally not complete when run in the iPython notebook, because running git push will prompt for your git username and password, which the jupyter notebook can't pass thru... but you can run it on a console, and enter your info from the prompt."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Advanced Options\n",
"\n",
"The above is the basic workflow for collaborating with people where you already have commit privileges; however, this is rarely the case outside of repositories that you haven't created. Below, we'll go over a few common, but more advanced workflows for using git.\n",
"\n",
"## Contributing to a repo via pull request\n",
"\n",
"If you don't have write permission for a repo, you can still suggest changes. This often how community software progresses; you may find a bug which is simple to fix in a popular package, and want to fix it for *everyone*. The process for doing this is similar to the basic workflow, but starts with forking the repo before you clone. Forking copies the repo for you in github, and makes you the owner, so that you can push changes. \n",
"\n",
"![image of fork option](images/fork.png)\n",
"\n",
"If you are associated with any organizations, you'll have to select where to fork to (personal or organizational)\n",
"\n",
"![confirm fork](images/fork_confirm.png)\n",
"\n",
"Once you've forked the repo, you can clone as before--only you'll be cloning **your** fork:\n",
"\n",
"![cloning the fork](images/clone_fork.png)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Generally, it's best practice to create a new branch for the feature you're adding of the bug that you are fixing. This is so that you can work on multiple seperate features if you'd like. Say for example, you're working on a new algorithm that will take several months to finish...but have a smaller change you want to make (and push) in the meantime. For now, we'll just branch to our github user name--note that we git pull before git pushing, to make sure we're on the most recent version of the repo. \n",
"\n",
"```\n",
"git branch espg\n",
"git checkout espg\n",
"touch espg.txt\n",
"git add espg.txt\n",
"git commit -m \"changed files\"\n",
"git pull\n",
"git push\n",
"```"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Make our changes, and push as before (again, we need to do this in console because of the username and password prompt). Once we do this, we can select the `New Pull Request` option in the github web interface, which allows you to enter text and images via markdown, as well as for the repo owners to comment on your work and request changes if they need:\n",
"\n",
"![PR button](images/PR_button.png)\n",
"\n",
"*You can choose which branch to submit the PR to and from*\n",
"\n",
"![Confirm PR](images/Confirm_PR.png)\n",
"\n",
"*Mark down interface*\n",
"\n",
"![PR Form](images/PR_form.png)\n",
"\n",
"This **PR** workflow is actually pretty common, since it puts a review step in place--it's how the tutorials you're using were put together by the instructors. Once the repo owners who have read/write access decide, your code is merged. Until then, you can see your pull request listed on *their* repo, and other people can comment and view your work. \n",
"\n",
"![requested PR](images/requested_pr.png)\n",
"\n",
"This can actually recurse a bit too; if you're working on something that other people like, they can send you a pull request merge their code into your pull request. Yes, pull requests can have there own pull requests too!"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Making commits less painful with ssh\n",
"\n",
"As you may have noticed, pushing can be a bit of a hassle with passwords. Git allows you to use ssh-keys instead, so that you don't have to input your username or password when you push. [Generating ssh-keys](https://help.github.com/en/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent) is a bit outside the scope of this tutorial, but github [has a good tutorial](https://help.github.com/en/github/authenticating-to-github/connecting-to-github-with-ssh) for what to do. What we can show quickly is how ssh-keys work in practice once you have them install on your system. Note that ssh-keys come as pair, with both a private key and a public key. The private key stays on your computer, but the public key get uploaded to github; this is done per computer, so here for example are my public keys (under the 'settings' github profile option):\n",
"\n",
"![github ssh keys](images/ssh_keys.png)\n",
"\n",
"There's one for both my laptop, and my work machine, so I can push from either. (Actually, multiple machines can use the same ssh-key, so 'talus' is on both of my personal machines). To tell git to use ssh, we just modify .git/config from:\n",
"\n",
"```\n",
"[remote \"origin\"]\n",
" url = https://github.com/espg/sample-repository.git\n",
"\tfetch = +refs/heads/*:refs/remotes/origin/*\n",
"```\n",
"\n",
"To:\n",
"\n",
"```\n",
"[remote \"origin\"]\n",
"\turl = [email protected]:espg/intro-git.git\n",
"\tfetch = +refs/heads/*:refs/remotes/origin/*\n",
"```\n",
"\n",
"The new remote line tells git to use ssh. If you already have your ssh keys setup, you can avoid modifying .git/config by just choosing the ssh option when you clone, and git will know to set the remote appropriately:\n",
"\n",
"![ssh option](images/ssh_option.png)"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"collapsed": true
},
"outputs": [],
"source": []
}
],
"metadata": {
"kernelspec": {
"display_name": "Python 3",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.7.6"
}
},
"nbformat": 4,
"nbformat_minor": 4
}
Loading

0 comments on commit 45fc4cb

Please sign in to comment.