BCB 546X -- 8 Sep 2017

class: center, middle

# More Fun with Git

???

Notes for the _first_ slide!

---

# ♥ Git ♥

## Creating a Repository

Let's create a new Git repository and host it on GitHub using our accounts (for the demo, 
I will create the repo in the [EEOB-BioData](https://github.com/EEOB-BioData) organization
so that everyone will have easy access to it).

<br>

But first, let's tell Git who you are

```
$ git config --global user.name "Ada Lovelace"
$ git config --global user.email "adal@analyticalengine.com"
```

---

# ♥ Git ♥

### Some helpful commands for your new repository

Initialize a new Git repository

```
$ git init
```

After a file has been added or modified, you can stage the file

```
$ git add README.md
```

Commit the file to your local repository and write a message

```
$ git commit -m "initial commit (README.md)"
```

---

# ♥ Git ♥

### Some helpful commands for your new repository

After you have made your commit, the repository is up-to-date locally. Next you need to connect
your local repo to the remote.

Add the remote

```
$ git remote add origin git@github.com:username/repo-name.git
```

Push your snapshot to the remote

```
$ git push -u origin master
```

---

# ♥ Git ♥

## Git can be challenging

<br>

* What do you find confusing?

* What did you struggle with when creating a repository?

* What do you think would be helpful to overcome these challenges?

---

# Git Conceptual Road Map

(image source [http://blog.podrezo.com/git-introduction-for-cvssvntfs-users](http://blog.podrezo.com/git-introduction-for-cvssvntfs-users/))

---

# Git Best Practices

* Commit often. Keep commits small and frequent. This also helps you have informative commit messages

* Make sure every commit "works". Never commit if it doesn't compile, runs with errors, 
or requires files that only exist in your workspace. Since commits are snapshots, this should mean a working snapshot.

* Write commit messages that will be readable and useful to others and *future-you*. (This is really difficult.) Also, remember when your repository is public, anyone can see your commit messages.

* Use multiple branches. This is one of Git's most powerful features and enhances collaboration and reproducibility. You should
also decide on a [workflow](https://www.atlassian.com/git/tutorials/comparing-workflows) (like [this](https://guides.github.com/introduction/flow/) or [this](http://nvie.com/posts/a-successful-git-branching-model/)).

---

# Git Best Practices

* **Pull from the remote before you do anything in your repository.** This reduces potential merge conflicts. So before you make
changes to any files `git pull`, after you make a commit and before you push `git pull`.

* Don't commit unnecessary files. Often these are files that may be generated by your project 
and can lead to merge conflicts. 
You can keep these files in your working directory without being tracked using the `.gitignore` file
(or the `~/.gitignore_global` file in your home directory).

* Review your changes before committing.

* Use aliases. You can add specific aliases for Git commands in the `.gitconfig` file that lives in your home directory.

```
[alias]
hist = log --graph --pretty=format:'%h %ad | %s%d [%an]' --date=short
last = log -1 HEAD
ci = commit
st = status
```

---

# Markdown

[Markdown](https://daringfireball.net/projects/markdown/) is a text-based mark-up language that is easily rendered
into HTML

* It has become a staple of reproducible science:

* it can be rendered on GitHub (also Bitbucket & GitLab) and makes online repositories more readable and accessible
--

* it is used as a notebook interface for R ([Rmarkdown](http://rmarkdown.rstudio.com/))
--

* it is used as the markup language for [Jupyter](http://jupyter.org/) notebooks, which provide a notebook interface for many languages, including Python and R
--

* There are some freely available editors that make writing in Markdown pretty easy

* Windows and Linux: [REMARKABLE](https://remarkableapp.github.io/)
    * Mac OSX: [MacDown](http://macdown.uranusjr.com/)

* I made all my slides using Markdown and a HTML template called [Remark](https://remarkjs.com)

---

# Markdown

## Let's see some Markdown

* It is recommended that all README files on web-based Git hosts be written using Markdown

* The file extension for a Markdown file is `.md`

* I will demonstrate in MacDown with our `README.md` file for `Week_03`

---

# Your First Repository

### Your Challenge

* Create a new repository on GitHub

* Write a description of the repository in the README.md Markdown file

* Create a new text or Markdown file that says "Hello world" or anything else you'd like to say

* Add this file to your repository and push all the changes to the remote

Let's take some time to make sure everyone can create a repository. If you have been successful, please help your classmates.

---

# Get Help

## No matter the problem (with Git or anything else in this class), someone else has encountered it already.

Google is an immensely powerful tool for troubleshooting computational problems

If you can articulate your problem in the form of a Google search query, you will likely find the answer online

These will primarily be on [Stack Overflow](http://stackoverflow.com/), like my [recent search](http://stackoverflow.com/questions/7155870/why-unicode-character-for-hearts-symbol-fails-with-html) for how to include 
Unicode emoji characters in my Markdown presentation 😎 💻

If your problem is unique, you can always submit a question on Stack Overflow

---

# Working with Others

Once you start working with other people on the same repository, you will encounter some scenarios that we haven't yet covered.

*What happens when two people commit changes to the repository at the same time?* ???

*What happens when two people commit changes to the same part of the same file at the same time?!?*

*What if I really disagree with the changes someone made to the repository?*

<br>

Let's demonstrate what happens when we merge...

???

to revert (hard) use `git reset`

can checkout previous commits temporarily.

---

# Git GUIs

## Graphical user interfaces for Git

There are several [GUI tools](https://git-scm.com/download/gui/linux) for working with Git

These tools may be very helpful for doing things that you don't do every day (when it's difficult
to remember the command)

They also provide nice ways to visualize your repository tree and `diff` commits, etc.

I like [SourceTree](https://www.sourcetreeapp.com/).

---

# GitHub Pages

### GitHub provides hosting for websites ([https://pages.github.com](https://pages.github.com/))

* You can create a *free* website hosted on GitHub simply by creating a repository in your account called
`username.github.io`

* For example, Wade Dismukes (a student in EEB) created his site in GitHub pages: [https://wadedismukes.github.io](https://wadedismukes.github.io/)

* My lab website ([http://phyloworks.org](http://phyloworks.org)) is hosted on [GitHub](https://github.com/phyloworks/phyloworks.github.io), using a [Bootstrap](http://getbootstrap.com/) CSS template.
If you [purchase](https://www.namecheap.com/) your own domain, it is simple to [redirect](https://help.github.com/articles/using-a-custom-domain-with-github-pages/) your GitHub Pages site to the new domain.

* You can create a website for any GitHub project repository, simply by enabling GitHub Pages in your settings

* The [website for our course](https://eeob-biodata.github.io/BCB546X-Fall2017/) is rendered in HTML by GitHub Pages, too. We do this by simply enabling GitHub Pages in the _settings_ of our repository. Then we chose a theme for our pages (i.e., the Minimal theme). These themes run [Jekyll](https://jekyllrb.com/) and there are some nice [Jekyll pages](http://jekyllthemes.org/) out there.

---

# Git Collaboration

### Now that we all have repositories on GitHub, let's collaborate!

* Get into groups of 2-3.

* Give your collaborators access (push rights) to your repository by inviting them on the GitHub page for your repository

* Clone your collaborator's repository

* Add and edit files in your collaborator's repository

* Commit and push those changes to the remote