outline

introduction
- why bother?
- workflow
- fork & pull model
- github features
exercises
1. hello world
  - http://github.com/[user]/hello-world
2. create a website repo
  - http://[user].github.io
3. fork & pull a repo
  - stevejbrown/rss_article_recommender

why bother?

backup to offsite archive (ie github.com)
rewind changes (ie versioned files)
document file changes with issues and messages
collaborate with others
publish to free web site

example workflow

sign up at github.com (1x/user)
install git (1x/machine)
create [or fork] a repository, aka "repo" (1x/repo)
clone from web to your local desktop (1x/repo)
[branch copy for isolated development of a feature (1x/feature)]
commit changes locally
push changes to your repo
[pull request changes from your repo to source repo that was forked)]

models of development

fork & pull: open-source / big teams
- fork a source repo (read only)
- push changes to a personal repo
- pull request to commit to a source repo
shared: small teams
- push changes directly to a repo (read + write)
branching: sandbox changes with either of above modes
- See flow

fork & pull model

	`github.com/[user0]/[repo]` (orig, web)	`github.com/[user]/[repo]` (you, web)	`~/github/[repo]` (you, local)
(1x)		fork	clone
			commit
			branch
			push
	merge	pull request

where:

[user0] is the original user or organization
[repo] is a repository
[user] is your github username (eg bbest)

github features

track changes, issues, etc. free for public repos
max: 1GB per repo, 100MB per file. so larger files (and binary) on file server, with remote vpn option
render markdown, eg README.md
special rendering of various popular file formats (txt/md, png/jpg, csv/tsv, geojson/topojson) ...

github rendering: text

Track Changes view with "Rendered" button to view differences between versions of a text file: additions in green, removals in red strikethrough. Details: Rendering differences in prose documents

Source

Rendered

github rendering: images

Image view show differences in 3 ways: 2-up, swipe and onion skin views. Details: Rendering and diffing images

Onion Skin

github rendering: csv

CSV view allow for on the fly tabular view, searching for text, and linking to specific rows of data. Details: Rendering CSV and TSV data.

select rows, URL to select

github rendering: geo

Geographic view of GeoJSON or topojson files render automatically as a map. Details: Mapping geoJSON files on GitHub

interactive map with zoom, click on details, OpenStreetMap

ex 1: hello world

Create a hello-world repository and tour some of Github's most useful features. You only need a web browser and Github account (no git or other desktop software required).

Sign up for a new GitHub account
Follow the GitHub Guide Hello World to walk through essentials of: repositories, branches, commits, issues and pull requests.

ex 2: create a website repo

Create a website repository in Github. You only need a web browser and Github account (no git or other desktop software required).

Create repo [user].github.io, where [user] is your github username
- Commit your first change on README.md
Create pages
- Have fun picking a theme!

This is how we created the website for the ucsb-data-science:
- edit: github.com/ucsb-data-science/ucsb-data-science.github.io
- view: ucsb-data-science.github.io

ex 3: fork & pull a repo

Fork the repo stevejbrown/rss_article_recommender.

Set up git if you haven't already
- git + github applications recommended
Fork the repo
1. Fork this repository: https://github.com/stevejbrown/rss_article_recommender
2. Clone your forked repo to your desktop
```
mkdir ~/github
cd ~/github
git clone https://github.com/[user]/rss_article_recommender.git
cd rss_article_recommender
```
3. Edit files. For the sake of testing, create a new file [user].txt where [user] is your Github username. We'll start with each of us editing different files so as to avoid merge conflicts.
4. Commit changes and push

md to html slideshow

This presentation was created in markdown (see index.md) and rendered as an HTML slideshow with pandoc. Details: Producing slide shows with Pandoc. To render the HTML, the content was placed in the gh-pages branch of the ds-git repo.

Here's some code to get the idea:

# clone "ds-git" repository made on github.com to local machine
cd ~/github
git clone https://github.com/bbest/ds-git.git

# create new "gh-pages" branch
cd ds-git
git checkout -b gh-pages

# create document index.md in editor like http://atom.io

# convert from markdown (*.md) to html slidy with options
pandoc \
  -t slidy \
  --self-contained --incremental --slide-level=2 \
  --css=octicons/octicons.css \
  index.md \
  -o index.html

# check status, note untracked files
git status

# add files for git tracking, and commit changes locally
git add *
git commit -a -m 'initial presentation'

# push to remote, set upstream (1x)
git push -u origin gh-pages

# push (after 1x)
git push

To see all the pandoc options:

pandoc --help

Also set the default branch to gh-pages, since master not otherwise being used.

git & github

introduction