Notes on Using Git

class: center, middle, title-slide

.title[
# Notes on Using Git
]
.author[
### Luke Tierney
]
.institute[
### University of Iowa
]
.date[
### 2023-03-01
]

---

## Reasons For Using Git and GitLab/GitHub

You have been using `git` to submit your work to GitLab.

But that isn't what `git` is really about.

`git` is a *version control* (VCS) system; these are also called
*revision control systems* (RCS) or *source code management systems*
(SCMS)).

What version control systems do for you:

* Provide backup against accidentally deleting files or chunks of files.

* Allow you to find where a change was made that caused problems.

* Allow you to revert to a previous version of your file, or to
  reverse a change you made.

With a remote repository:

* Provide backup against your computer failing.

* Synchronize your work across multiple computers

* Allow you to collaborate with others.

---

## Good Git Habits

To take advantage of these capabilities you need to develop some good
practices:

* Do all your work in your repository; don't just copy things there at
  the last minute.

* Commit and push often:

* Each time you complete a substantial chunk of work (e.g. finish
      a problem or a part of a problem).
    * Each time you take a break.
    * Each time you run into a problem (include a reminder of the
      problem in your commit message).

* Your commit message should be concise but useful.

* You can provide more extensive information in a second paragraph

* Not sure if RStudio shows this, but GitLab and the command line
     `git` do.

* Pushing often also lets you know early if there is an issue with
  GitLab access.

* If you are using Windows and `https`, after changing your HawkID
      password you may need to use the **Credentials Manager** to
      remove the old authentication information for GitLab.

---

layout: true
## Working With Git

---

If all goes well:

* If you are working on your own and on only one computer, all you
  will need to do with `git` is:

* Commit changes to your local repository.

* Push changes to your remote GitLab repository.

* If you are using several computers, or collaborating with someone,
  you will also need to `pull` changes from GitLab.

If you run into issues, you will need to use some more `git` tools.

---

The most common operations are well supported by RStudio or GitLab:

* Finding what changes were made to a file.

* Retrieving an older version of a file.

Other operations are easier, or only possible, using the command line:

* Moving and Renaming files.

* Reversing a particular change.

---
layout: false

### `git` Operations with RStudio

You can perform `git` operations with:

* The **Tools** > **Version Control** menu.

* The **Git** tab.

Examples:

* Make a change, longer commit message, push.

* Review history, get old file versions.

* Create folders, renaming files.

### `git` Operations with GitLab

* Review history, get old file versions.

* Check out `Blame` tab.

---
layout: true
### Using Command Line `git` in a Shell/Terminal
---

#### Set Up a Reasonable Editor

Occasionally `git` will want to open an editor to let you enter a
commit message.

You can prevent this by specifying a message on the command line with
the `-m` option.

The default editor it uses (usually `vi` or `vim`) is probably not
useful.

You can register a more reasonable editor using

``` shell
  git config --global core.editor <editor>
```

Replace `<editor>` with the name of a program that opens your editor
when run from the command line with a text file argument.

* On Linux you can use `gedit` or `nano`; `nano` works on the notebook server.

* On Windows `notepad` should work.

* On Mac OS you should be able to use `nano`.

Or use your favorite editor if you have one.

---

You only need to do this once on each system you use.

* The information you provide is included in a `.gitconfig` file in
  your home directory.

If you don't do this you may end up with `git` using the `vi` or the
`vim` editor, which is powerful but not intuitive if you haven't used
it.

* If you end up in `vi`, type `:q<return>` to get out.

---

#### Common Commands

* `git clone <repository> [<directory>]`
* `git status`
* `git pull`
* `git add <file1> <file2> ...`
* `git commit` or `git commit -m "<message>"`
* `git push`

#### Other Commands

* `git log [<file>]`
* `git blame <file>`
* `git mv <oldname> <newname>`
* `git show <REVHASH>:<filepath>`

---

#### Examples

* Log, blame
* Create, rename
* Change, longer commit message

---
layout: false

## Conflicts

It you work on several computers, or collaborate with someone, you may
need to resolve conflicts.

* Conflicts are marked with

```shell
<<<<<<
    ...
======
    ...
>>>>>>
    ```

* Remove the markers and adjust the code.

* Some editors provide some support for this.

---

## Reverting a Specific Commit

The `git revert` command allows you to revert a specific commit.

`git revert --help` provides some documentation.

This can lead to conflicts that will need to be resolved.

---

## GitLab/GitHub features

[GitLab](https://about.gitlab.com/) and [GitHub](https://github.com/)
are _social coding platforms_.

In addition to providing a remote repository, they provide a number of
facilities to aid in collaboration.

Two important facilities are:

* _Issues_ for reporting and discussing bugs and other issues.

* _Merge requests_ (called _pull requests_ in GitHub) for managing the
  incorporation of proposed changes.

Issues can be _assigned_ to someone to deal with; assigning an issue
will generate an email to the assignee.

---

## Some Useful Resources

- [Happy Git and GitHub for the useR](https://happygitwithr.com/).
- [A Quick Introduction to Version Control with Git and GitHub](https://journals.plos.org:443/ploscompbiol/article?id=10.1371/journal.pcbi.1004668)
- [git/github guide: a minimal tutorial](https://kbroman.org/github_tutorial/)
- [Top 10 Git Tutorials for Beginners](https://www.webfx.com/blog/web-design/git-tutorials-beginners/)
- [Git Immersion](https://gitimmersion.com/)
- [Git Cheat Sheet](https://github.com/tiimgreen/github-cheat-sheet?utm_content=buffer096d6&utm_medium=social&utm_source=twitter.com&utm_campaign=buffer)
- [Graphical user interfaces for Git](https://git-scm.com/downloads/guis/)

//adapted from Emi Tanaka's gist at //https://gist.github.com/emitanaka/eaa258bb8471c041797ff377704c8505