Get started with git

<p style="text-align:center">University of Newcastle | Applied Maths Seminars | 2024 Nov 14</p>

# Get going with git

## Set up

Please send an email to `dave.smith@newcastle.edu.au` with subject *Get going with git* so I can invite you to GitLab.

---

## Installation & set up

From the software centre, install Git for Windows, latest version.

Then follow the link in the invitation email to set up your GitLab account.

---

## What are git, GitLab, GitHub?

* git is version control software. git is distributed and works well for teams of one to thousands.
              * GitLab/GitHub are websites that act as centralized repositories for software with extra features like project management and CI/CD. Each repository on GitLab/GitHub can be public or private.

---

## Configure git (once per computer)

Open Windows PowerShell from Windows Start Menu

```powershell
              Set-ItemProperty -Path HKCU:\Environment\ -Name Home -Type String -Value $Env:UserProfile
              ```

</div>

Open Git Bash from Windows Start Menu
              ```bash
              git config --global core.editor "nano"
              git config --global user.name "Your name"
              git config --global user.email youremail@uon.edu.au
              cd ~
              ssh-keygen -t ed25519 -C "For GitLab"
              cat ~/.ssh/id_ed25519.pub
              ```
              Highlight and copy the last output.
              Go to [GitLab user settings](https://gitlab.com/-/user_settings/ssh_keys), click Add new key and paste the key.

---

## Git philosophy of version control

* You should save inputs, not outputs.
              * Changes are recorded per line, per file.
              * Changes are recorded in a digraph, allowing
                * Recording a collection of edits in *commit* which has a *message* describing what it does and a timestamp and UUID identifying it.
                  
                * Branching (like a tree). The default branch is called `main`.
                * Recombining commits from two branches with common parent is *merging* or a *three way merge*.

</div>

![A graph of git commits on branches](gfx/git-graph.webp)

</div>
              </div>

---

## Git philosophy of version control

* Everyone working on the repository has their own copy of the repository, can edit simultaneously and combine their edits by merging.
              * Other people's copies of the repository are remembered by your repository as *remotes*, and the remote you first downloaded from is called `origin`.
              * You don't automatically get everyone else's changes; you have to pull from / push to the remotes.

---

## Git workflow

* Identify problem (bug / improvement)
              * Create and checkout a new branch
              * Fix problem
                * Edit text file to improve solution to problem
                * Stage changes
                * Commit with message recording progress
              * Merge
              * Push

---

## Structure of a git repository

* All files stored in directory
              * `.git` subdirectory stores all the version history
              * `.gitignore` tells git what files not to track

Note:
              All files are stored in a directory, just as you would usually keep all project files together. As usual, it's wise to use subdirectories for complex projects with many files.<br>
              The (usually hidden) `.git` subdirectory which contains all the data git needs to do its verison control. Do not go in here unless you are an expert in git.<br>
              Various (most usually hidden) config files for git are also in the main directory. The most important is `.gitignore`. This is used to tell git not to track certain files, file types, or subdirectories.

---

## Tips for tex files & git

* New line for each sentence
              * New line for each part of a complicated equation
              * LaTeX is more sensitive to whitespace than most languages, so:
                * You may need to add # at the end of a line for LaTeX to run properly
                * Don't "automatically delete empty lines"
              * Commit `tex` and `bib` files, not `log`, `bbl`, or `pdf` files

---

## Using Git Gui / Git Bash

We will demonstrate using Git Gui and Git Bash on Windows to go through the workflow

---

### Clone

You only need to do this once per repository per computer.
              If you ever want to "unclone" later, just delete the directory for the repository; the files git uses for version control will be deleted too.

Warning: Never clone into a directory that is synched to OneDrive, Google Drive, etc., because these services can interact poorly with git.

---

#### Clone: Git Gui

1. GitLab Project > Code > Clone with SSH copy URL<br>
              1. Start Menu > Git Gui > Clone Existing Repository<br>
              1. Paste into Git Gui Source Location<br>
              1. Browse for Target Directory then append a new directory name<br>
              1. Click Clone button

</div>
              <div class="l-align-column">

#### Clone: Git Bash

1. GitLab Project > Code > Clone with SSH copy URL<br>
              1. Start Menu > Git Bash
                 ```bash
                 mkdir ~/research
                 cd ~/research
                 git clone CLONEURL
                 ```
                 where `CLONEURL` is replaced by right click > paste.

Note:
              This will automatically create a new directory within `research` with the repository's name, unlike in Git Gui, where you have to specify explicitly the directory to be created in the Target Directory field.

</div>
              </div>

---

### Branch

Git branches each have a name, which should be short but describe the purpose of the branch.
              The name cannot contain spaces, but `-` and `_` are ok.

* `some edits` is not allowed.
              * `some-edits` is allowed but bad.
              * `allow-complex-valued-intial-data` is good and allowed.

---

#### Branch: Git Gui

Branch > Create<br>
              Enter `correct-proof` for the branch name and click Create.
              The current branch is shown in the top left.
              It should now be `correct-proof`.

</div>
              <div class="l-align-column">

#### Branch: Git Bash

`git checkout -b correct-proof`.<br>
              You can check `git status` to see the branch you are on.

</div>
              </div>

---

### <span class="fragment highlight-current-bg-red" data-fragment-index="2">Edit</span>, <span class="fragment highlight-current-bg-red" data-fragment-index="3">Stage</span>, <span class="fragment highlight-current-bg-red" data-fragment-index="4">Commit</span>

<span class="fragment highlight-current-bg-red" data-fragment-index="2">Make some edits to the tex file.</span>

<span class="fragment highlight-current-bg-red" data-fragment-index="3">Select the tex file to tell git this what we want to change.</span>

<span class="fragment highlight-current-bg-red" data-fragment-index="4">Tell git to record the change in a commit.</span>

---

### Edit, Stage, Commit

#### Git Gui

1. Click Rescan if necessary.
              1. Select the files you edited under Unstaged Changes. Commit menu > Stage To Commit.
              1. Type a commit message.
              1. Click Commit button.

</div>
              <div class="l-align-column">

#### Git Bash

1. ```bash
                 git add .
                 git commit
                 ```
              1. Type your commit message.
                 Finish editing with `Ctrl+X, y, ⏎`.

Alternatively, commit and enter short message with `git commit -m "your message here"`

</div>
              </div>

Note:
              There is a standard for commit messages.
              Write a title with no more than 72 characters ending in `.`.
              Then leave a blank line.
              Then write whatever you like.
              This section can contain markdown.

---

### Merge

Combine all the commits from a merged branch into the branch we are currently working on.

Do this after completing work on a feature branch that you want to put into the main branch.

---

#### Merge: Git Gui

1. Branch menu > Checkout Branch.
              1. Select branch `main` and click Checkout.
              1. Merge menu > select `correct-proof` and click Merge.
              1. Click Close button.

</div>
              <div class="l-align-column">

#### Merge: Git Bash

```bash
              git checkout main
              git merge correct-proof
              ```

</div>
              </div>

Note:
              Before merging, you checkout to the branch you want to merge **merge into**.
              When doing the merge, you select the branch whos changes you want to apply to the branch you checked out.
              The checked out branch now has all the commits of the merged branch.
              The merged branch also remains as it was; unaffected by that merge; You can keep working on it and merge more changes later.

---

### Push

Share your commits to the GitLab server.

---

#### Push: Git Gui

1. Click Push button.
              1. Select `main` Source Branch and click Push button.
              1. If you want the `correct-proof` button to be stored on the remote (GitLab) then push that branch also/instead.
              1. Click Close button.

</div>
              <div class="l-align-column">

#### Push: Git bash

`git push`.

Or use `git push origin BRANCHNAME` to push a different branch.

</div>
              </div>

Note:
              If you are working in parallel on two computers, or if a collaborator pushed since you last did, then you will have to `pull` first, to get the updates from the remote GitLab server.
              The pull will get the updates and automatically merge them.
              Then you can push the fully updated branch.

---

## More git

* Git Gui or Git Bash → plugins for modern text editors
              * Git visualization software:
                * GitHub Desktop free,
                  ![Windows](gfx/win.svg)
                  ![Mac](gfx/mac.svg)
                  ![Linux](gfx/linux.svg) (community fork),
                  in software centre
                * Sourcetree free,
                  ![Windows](gfx/win.svg)
                  ![Mac](gfx/mac.svg),
                  not in software centre
                * Gitkraken free for students,
                  ![Windows](gfx/win.svg)
                  ![Mac](gfx/mac.svg)
                  ![Linux](gfx/linux.svg),
                  not in software centre
              * [git cheatsheet by Atlassian](https://www.atlassian.com/git/tutorials/atlassian-git-cheatsheet); more git cheatsheets are easy to find
              * [git book](https://git-scm.com/book/en/v2) for git philosophy & advanced git techniques
              * Once you are comfortable with branching, staging, committing, merging, pulling, and pushing, try learning about `.gitignore`, init, stash and then rebase

Note:
              Modern text editors include VSCodium, VSCode, Zed, Eclipse, Sublime.

The Git book gives a much fuller and very clear explanation of the git philosophy which will help you understand why things are done the way they are.
              Be aware that a lot of git resources online still use the name `master` for the main branch instead of the more modern `main`.
              You can always safely substitute `master` for `main`, except for interaction with Overleaf, which requires you to use the `master` branch.

---

## Git workflow

* Identify problem
              * Create and checkout a new branch
              * Fix problem
                * Edit text file to improve solution to problem
                * Stage changes
                * Commit with message recording progress
              * Merge
              * Push

</div>

---

## Git workflow integrating GitLab

* Identify problem
              * Create GitLab Issue to track it & associated branch
              * Pull the new branch
              * Fix problem
                * Edit text file to improve solution to problem
                * Stage changes
                * Commit with message recording progress, referencing the GitLab issue with `Progress on #6`
              * Push the new branch
              * Merge Request and merge on GitLab

</div>

---

## More GitLab

Learn next
              * Create projects
              * Use issues, issue branches, merge requests
              * Use Markdown in issues; see [GitLab Flavored Markdown](https://docs.gitlab.com/ee/user/markdown.html).
              * Manage users associated with a project; invite your collaborators

</div>
              <div class="l-align-column">

Productivity & project management
              * (Kanban style) Boards
              * Milestones
              * In browser text editor

For software development
              * Automated test runners every time you push a commit
              * CI/CD: automated deployment

</div>
              </div>

---

## Git and backup

Git, even with GitLab, is not a backup solution.

But git can be used as part of a backup solution, if you
              * Regularly / automatically pull to multiple computers
              * Push to not just to `origin` but also to a backup repository on a portable hard drive
              ---
              <p style="text-align:center">
                These slides are available at
              </p>

![qr code for URL of slides](q/index.svg)