Week 3 - Part II - Remotes, branching, and merging

class:inverse middle center

## *Week 3: Git and GitHub*

----

# Part II: Remotes on GitHub, and branching & merging

### Jelmer Poelstra
### 2021/01/28

---
class:inverse middle center

# Overview

----

.left[
- ### [Remote repositories on GitHub](#remote)
- ### [Branching & merging](#branch)
- ### [Some Git best practices](best-prac)
]

---

## Getting set up at OSC

- **Launch VS Code**: 
 Go to <https://ondemand.osc.edu> => `Interactive Apps` =>
 `Code Server` => 1 or 2 hours => `Launch` ... => `Connect to VS Code`.
 
- **Open your workspace**: 
 On the *Welcome* page, under the heading `Recent`,
 your workspace should be listed ("`<workspace-name> (Workspace)`").
 
- **Open a terminal in VS Code:** 
 (<kbd>Ctrl</kbd>+<kbd>backtick</kbd> or
 
 => `Terminal` => `New Terminal`),
 and issue the command `bash` to break out of the Singularity shell.

----

- **Load the Git module:**
  ```sh
  $ module load git
  ```

- **Move to the following dir:**
  ```sh
  $ cd week03/originspecies # From /fs/ess/PAS1855/users/$USER/
  ```

---
class:inverse middle center

# Remote repositories on GitHub

----

---

## Remote repositories

We have been locally version-controlling our `originspecies` repo,  
but now we also want to **put this repo online**, to:

- Share our work and/or

- Have an online backup and/or

- Collaborate with others.

We will use the **GitHub website** as the place to host our online repositories.

.content-box-info[
Online counterparts of repositories that we also have locally are usually
referred to as "remote repositories" or "remotes".

To add and manage remotes, we use the `git remote` command.
]

---

## Creating remote repositories

While we can *interact* with online repos using Git commands,  
we **can't _create_ a new online repo with the Git CLI**.

So, we need to go to the GitHub website to create a new online repo.

.content-box-info[
VS Code does provide functionality to create GitHub repos directly.
We may look at this later in the course, but if you're interested,
look for the `GitLens` extension by Eric Amodio.
]

---

## Create a GitHub repo (cont.)

1. Go to <https://github.com> and sign in.

2. In the top-right, click the `+` next to your avatar and then select  
   `New repository`.

---

## Create a GitHub repo (cont.)

1. Go to <https://github.com> and sign in.

---

## Create a GitHub repo (cont.)

1. Go to <https://github.com> and sign in.

2. In the top-right, click the `+` next to your avatar and then select  
   `New repository`.
   
3. In the box `Repository name`, we'll use the same name that we gave to our
   local directory: `originspecies`.  
   (*Note:* these names don't *have to* match up.)
   
4. Leave other options as they are.  
   (We're not adding a README or other files as we are "importing" an
   existing repository: our local repo.)

---

## Create a GitHub repo (cont.)

1. Go to <https://github.com> and sign in.

5. Click `Create repository`.

---

## Link up the local and remote repositories

.content-box-info[
You can click on the `HTTPS`/`SSH` button to change the URL type.
]

---

## Link up the local and remote repositories (cont.)

We go back to the shell, where we'll enter the commands that GitHub provided
to us under "*...or push an existing repository from the command line*".

- First, we tell Git to add a "remote" connection with `git remote`.  
  We provide three arguments to this command:
  
  - `add` &ndash; because we're adding a remote.
  
  - `origin` &ndash; the nickname we're giving the connection.  
    This is an arbitrary name but is usually *origin* by convention.   
  
  - The SSH URL to the GitHub repo.

```sh
 # git remote add <remote-nickname> <URL>
 $ git remote add origin git@github.com:<user>/originspecies.git
 ```

---

## Link up the local and remote repositories (cont.)

- Second, we rename the default branch, from `master` to `main`
  (GitHub since recently uses `main` as the default branch):
  ```sh
  $ git branch -M main
  ```

- Third, we push our local repo to remote using `git push`.  
  Whenever we push a branch for the first time,  
  we need to use the `-u` option to set up an "**u**pstream" counterpart:
  ```sh
  $ git push -u origin main
  ```

.content-box-info[
When not given any arguments, `git push` pushes:
 - To & from the **currently active *branch*** (default: `master`/`main`)
 - To the **default remote connection**.

Therefore, from now on, we can mostly just use:

```sh
$ git push
```
]

---

## Explore the repository on GitHub

- Back at GitHub, click on `Code` in the lower of the top bars.  
  Now, we can see the files that we just uploaded from our local repo.

- Next, click where it says `x commits` (should be 4) with a clock icon,  
  and you'll get an overview of commits somewhat like with `git log`.

- On the right hand side, there are three buttons for each commit:

- Click the hash (hexadecimal ID) to see changes made by that commit.
 
 - Click the <kbd>< ></kbd> to see the state of the repo at the time
 of that commit.
 

<img src="img/github-commits.png" width="35%">

---

## Remote repos &ndash; Single-user workflow

In a single-user workflow, all changes are made in the *local repo*,  
and the remote repo is simply periodically updated (*pushed to*).

So, the interaction between local and remote is unidirectional:

---

## Remote repos &ndash; Single-user workflow

In a single-user workflow, all changes are made in the *local repo*,  
and the remote repo is simply periodically updated (*pushed to*).

So, the interaction between local and remote is unidirectional:

---

## Remote repos &ndash; Single-user workflow

In a single-user workflow, all changes are made in the *local repo*,  
and the remote repo is simply periodically updated (*pushed to*).

So, the interaction between local and remote is unidirectional:

---

## Remote repos &ndash; Single-user workflow

In a single-user workflow, all changes are made in the *local repo*,  
and the remote repo is simply periodically updated (*pushed to*).

So, the interaction between local and remote is unidirectional:

---

## Remote repos &ndash; Single-user workflow

In a single-user workflow, all changes are made in the *local repo*,  
and the remote repo is simply periodically updated (*pushed to*).

So, the interaction between local and remote is unidirectional:

---

## Remote repos &ndash; Single-user workflow (cont.)

In our day-to-day work, we now commit as usual, and in addition,  
*push* to remote occasionally:

- Let's add a README.md file, and commit:
  ```sh
  $ echo "# Origin" > README.md
  $ echo "Repo for book draft on my new **theory**" >> README.md
  $ git add README.md
  $ git commit -m "Added a README"
  ```

- Now, we push to the remote repository:
  ```sh
  $ git push
  ```

.content-box-info[
If we go back to GitHub, we see that the contents of the README.md
automatically shows up as a rendered Markdown file!
]

---