index.qmd

---
title: "Supercharge your research code with Git and GitHub<br>{{< fa brands git-alt >}} {{< fa brands github >}}"
format:
    revealjs:
        theme: custom.scss
        slide-number: true
        show-slide-number: speaker
        chalkboard: true
        code-line-numbers: false
        preview-links: auto
author: "**David Wilby**<br>[RSE Team](https://rse.shef.ac.uk/)<br>[**rse.shef.ac.uk**](https://rse.shef.ac.uk) | [**davidwilby.dev**](https://davidwilby.dev)<br><br>
**Chris Wild**<br>[Research & Innovation IT Team](https://students.sheffield.ac.uk/it-services/research)
"
date: 05/23/2023
date-format: "ddd Do MMMM YYYY"
footer: "these slides: [davidwilby.dev/carpentries-git-slides](https://davidwilby.dev/carpentries-git-slides) - {{< fa brands github >}} [improve this talk!](https://github.com/davidwilby/carpentries-git-slides)"
from: markdown+emoji
---

## 

![](assets/images/phd101212s.png){fig-align="center"}

“Piled Higher and Deeper” by Jorge Cham, [phd comics](http://www.phdcomics.com)

# Examples of version control (non-code)

* :books: Book editions
* {{< fa brands wikipedia-w >}} Wikipedia pages
* {{< fa brands google >}} Google docs

## What makes a version control system?

<br>

* :camera_flash: Snapshot current version
* :label: Name specific versions
* :leftwards_arrow_with_hook: Revert back to a particular version

<br>

Perhaps

* :books: Compare and merge versions


## Benefits of version control/source code management


. . .

**Local** :computer:

e.g. Git {{< fa brands git-alt >}}

* Protect against breaking *everything*
* Keep at least one working version of the code
* Snapshot your progress

. . .

**Remote** :globe_with_meridians:

e.g. GitHub {{< fa brands github >}}, GitLab {{< fa brands gitlab >}}

* Work collaboratively
* Share code easily
* Remote backup

## Without version control

<br>

. . .

:confused: Make changes by making a copy of the entire codebase.

<br>

. . . 

:neutral_face: Merging is a manual process.

<br>

. . .

:fearful: Lose track of which version contains what functionality.

<br>

. . .

:sob: Collaborating is just emailing zip files and crying.

<br>

# Version Control == Git

. . .

More often than not

## How does Git work?
```{mermaid}
%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'showCommitLabel': true, 'rotateCommitLabel': true}} }%%
gitGraph
    commit id: "commit 1"
    commit id: "commit 2"
    commit id: "commit 3"
    commit id: "commit 4"
    commit id: "commit 5"
    commit id: "commit 6"
    commit id: "commit 7"
```

::: {.callout-note appearance="simple"}

The most important concept in git is the `commit` - the name given to a unit of changes, and also to the process of making a commit.

:::


## Repositories (Repos)

<br>

::: {.callout-tip appearance="simple"}

<font size="6">Once a directory/folder is *initialised* with `git` it becomes a *repository*.</font>

<br><br>

:::

::: columns

::: {.column width="40%"}
**directory**
```
.
├── src/
├── LICENSE.md
└── README.md
```
:::

::: {.column width="20%"}

`git init`
------->

:::

::: {.column width="40%"}

**repository**
```
.
├── .git/
├── src/
├── LICENSE.md
└── README.md
```

:::

:::

. . .

::: {.callout-note appearance="simple"}

It's generally a bad idea to keep local repos in a managed location such as Dropbox or Google Drive.

Use GitHub or GitLab to make remote copies/backups.

:::


## Demo

<https://onlywei.github.io/explain-git-with-d3>

or

<https://bit.ly/git-sandbox>

or


{{< qrcode https://onlywei.github.io/explain-git-with-d3 width=350 height=350 >}}

## Firstly, a *linear* commit history
<br><br>
```{mermaid}
%%| fig-width: 15
%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'showCommitLabel': true, 'rotateCommitLabel': true}} }%%
gitGraph
    commit id: "commit 1"
    commit id: "commit 2"
    commit id: "commit 3"
    commit id: "commit 4"
    commit id: "commit 5"
    commit id: "commit 6"
    commit id: "commit 7"
```

## Branches  {{< fa solid code-branch >}}

Used to work on new features/changes/additions to the code.

```{mermaid}
%%| fig-width: 10
%%{init: { 'logLevel': 'debug', 'theme': 'base'} }%%
gitGraph
    commit id:"8bc2520"
    commit id:"2a70480"
    branch experiment
    commit id:"089e06b"
    commit id:"bec84f4"
    commit id:"2420edd"
```

```bash
git branch experiment
git checkout experiment
git commit
git commit
git commit
```


. . .


::: {.callout-tip appearance="simple"}

**Checkout**: switching to a different branch. 

Alternatively, `git switch`

(**Be aware** `checkout` command has many jobs, not just switching branches.

:::


. . .


::: {.callout-note appearance="simple"}

The default branch is now usually called `main` but is sometimes still `master`.

:::

## Merging  {{< fa solid code-merge >}}

<br>

Combine changes from two branches.

<br>

```{mermaid}
%%| fig-width: 10
%%{init: { 'logLevel': 'debug', 'theme': 'base'} }%%
gitGraph
    commit id:"8bc2520"
    commit id:"2a70480"
    branch experiment
    commit id:"089e06b"
    commit id:"bec84f4"
    commit id:"2420edd"
    checkout main
    merge experiment
    commit id:"60489ec"
```

```bash
git checkout main
git merge experiment
git commit
```


## Making a commit {{< fa solid code-commit >}}

```{mermaid}
%%| fig-height: 10
    flowchart TB
        A(Edit file) --> B
        B(Save) --> C
        C(Stage changes) --> D(Commit)
```

<br>

. . .

### Commits contain *changes*

Not actually *snapshots* of a file.

But can recreate a state from a sequence of changes.


## The commit hash

<br>

Git generates a hash string, uniquely identifying each commit.

::: {.callout-note appearance="simple"}

Git uses a "[Merkle tree](https://en.wikipedia.org/wiki/Merkle_tree)" under the hood. (Don't ask me how it works, I have no idea :shrug:)

:::

. . .

<br>

Hashes look like:

`d3dd03f493707256c8528bc83ad280a460f05a56`

. . .

<br>

But are most often seen as the first 7 characters, as this is easier to read/type and is normally enough to identify the commit.

`d3dd03f`


## The commit message

Each commit has a *message* associated with it.

<br>

**Summary/Title**: <50-72 characters

Displayed most frequently.

<br>

**Detailed description**: no character limit.

*Can* be used to capture more detail. Not used that often.

. . .

<br>

### This commit will...

::: columns

::: {.column width="30%"}

* :x: some stuff
* :x: code
* :x: updates

:::

::: {.column width="70%"}

* :heavy_check_mark: add new module "renderers"
* :heavy_check_mark: add new install instructions
* :heavy_check_mark: fix bug #17 with package update

:::

:::


## How to interact with Git

<br>

### command line `git`  {{< fa brands git-alt >}}
via unix shell (or gitbash/WSL on Windows)

```bash
$ git add README.md
$ git commit -m 'initial commit'
$ git status
```

<br>

::: columns

::: {.column width="50%"}

### IDEs
* [VSCode](https://code.visualstudio.com/)
* [RStudio](https://posit.co/download/rstudio-desktop/)
* [PyCharm](https://www.jetbrains.com/pycharm/)
* [Emacs](https://www.gnu.org/software/emacs/)

:::

::: {.column width="50%"}

### Other GUIs
* [GitKraken Client {{< fa brands gitkraken >}}](https://www.gitkraken.com/)
* [GitHub Desktop {{< fa brands github >}}](https://desktop.github.com/)
* [etc. etc.](https://git-scm.com/downloads/guis/)


:::

:::


## File types

**`Git` is great at handling _text_ files but NOT _binary_ files.**

::: columns

::: {.column width="50%"}

::: {.callout-tip icon=false appearance="simple"}

## What are text files?

Just plain text, e.g. files containing code such as:

* Plain text code files - e.g. .R, .py, .m, .cpp
* Plain text data files - e.g. csv

<br>

NOT documents such as

* .docx - Microsoft Word documents
* .pdf - PDF documents

These aren't text files, even though they primarily contain text.

:::

:::

::: {.column width="50%"}

::: {.callout-important icon=false appearance="simple"}

## What are binary files?

Files that need a specific program to read, including:

* .docx - Microsoft Word documents
* .xlsx - spreadsheets
* .pdf - PDF documents
* .fig - MATLAB figures
* .jpg, .gif - Images

<br>

**Note**: `Git` can handle binary files, but can't inspect what changes have been made, only that the file has changed. Making merging impossible.

:::

:::

:::


## Git learning resources

::: columns

::: {.column width="60%"}

* [Pro Git Book](http://git-scm.com/book/en/v2)
* [Software carpentry lesson](http://swcarpentry.github.io/git-novice/)
* *\"oh sh\*\* git\"* - [zine](https://wizardzines.com/zines/oh-shit-git/), or [blog](https://ohshitgit.com/)
* [The Turing Way](https://the-turing-way.netlify.app/reproducible-research/vcs.html)
* [stack overflow](https://stackoverflow.com/) *etc.* - *use carefully* :warning:
* blogs on [dev](https://dev.to/) or [atlassian](https://www.atlassian.com/git/tutorials) *etc.*

<br>

::: {.callout-warning appearance="simple"}
<font size="6">
**Remember**

Learning Git is a process.

Everyone makes mistakes.
</font>
:::


:::

::: {.column width="40%"}
[![](assets/images/ohshitgit.png)](https://ohshitgit.com/)
:::

:::

## Git {{< fa brands git-alt >}} vs GitHub {{< fa brands github >}} or GitLab {{< fa brands gitlab >}}

<br>

**Git**

* Local client for source code management
* Interacting with remote git servers

**GitHub/GitLab**

* Code hosting
* Collaboration
* OSS contribution
* Project management
* Automated workflows/continuous delivery


## Repositories

![](assets/images/talk_repo_screenshot.png)

## Issues

![](assets/images/github_issues_screenshot.png)

## Projects/Kanban Board

![](assets/images/github_projects_screenshot.png)


## Continuous integration/Automated testing

![](assets/images/githubactions_screenshot.png){fig-align="center"}