---
title: "saperlipopette"
vignette: >
  %\VignetteIndexEntry{saperlipopette}
  %\VignetteEngine{quarto::html}
  %\VignetteEncoding{UTF-8}
knitr:
  opts_chunk:
    collapse: true
    comment: '#>'
---

```{r}
#| label: setup
library(saperlipopette)
```

The goal of saperlipopette is to hold functions creating Git exercises, 
that users solve using their local and usual tools.


## Why this name?

This package is intended to be a companion to https://ohshitgit.com/,
so its name had to honour the exclamation.
"saperlipopette" is an [old-fashioned French exclamation (link including a recording to hear the word's pronunciation)](https://en.wiktionary.org/wiki/saperlipopette).
You can say "Saperlipopette, Git!".

## Example

Running the code below will create a new folder containing the exercise.
`parent_path` is a temporary folder created by the withr package, that will be deleted when closing the current R session.

If in RStudio or Positron, the code will even open a new R session. 
If not, the user will need to launch an R session,
where messages would indicate them what to do, 
and which URL to follow, to find, in this case, the corresponding ohshitgit entry.

```{r example}
library("saperlipopette")
parent_path <- withr::local_tempdir()
path <- exo_one_small_change(parent_path)
# what's in path
fs::dir_tree(path)
# with Git in a command line: git log
# or the gert R package
gert::git_log(repo = path)
```

In practice here, in the exercise's folder, the user would 
- change a file, 
- then Git add it through the terminal or the interface of their choice, 
- then run `git commit --amend --no-edit` through the terminal or the interface of their choice.

The user would examine the [Git history](https://git-scm.com/book/en/v2/Git-Basics-Viewing-the-Commit-History) before and after this, either through the terminal (`git log`) or the interface of their choice.

```{r, echo=FALSE}
source(system.file(
  "exo_one_small_change-Rprofile.en.R",
  package = "saperlipopette"
))
```

If they need more instructions than what is initially provided, the user can run:

```{r}
tip()
```

That interface relies on adding an `.Rprofile` to the newly created project,
with instructions formatted with the cli package.

We've set the Git author, committer and date so that the automatic commits get the same 
hashes, which can be useful when teaching a group: everyone should be looking at the same hashes on their machine, except for those commits they create themselves.

Below we use `gert::git_log()`, as opposed to `git log` in a command line, because that integrates better with R Markdown that we use for building documentation.

```{r example2}
parent_path <- withr::local_tempdir()
path <- exo_one_small_change(parent_path)
gert::git_log(repo = path)
parent_path2 <- withr::local_tempdir()
path2 <- exo_one_small_change(parent_path2)
gert::git_log(repo = path2)
```

### Multilingual!

The saperlipopette can create messages in English (default) but also in French and Spanish.
Example in French:

```{r example-fr}
library("saperlipopette")
withr::local_language("fr")
parent_path <- withr::local_tempdir()
path <- exo_one_small_change(parent_path)
# what's in path
fs::dir_tree(path)
# with Git in a command line: git log
# or the gert R package
gert::git_log(repo = path)
```

```{r, echo=FALSE}
source(system.file(
  "exo_one_small_change-Rprofile.fr.R",
  package = "saperlipopette"
))
```


```{r}
tip()
```

## Exercises

Consult the [reference](https://docs.ropensci.org/saperlipopette/reference/index.html).

Exercises cover:

- Oh Shit, Git!: exercises inspired by https://ohshitgit.com/ by Katie Sylor-Miller.
- Clean history: exercises on how to get a clean Git history, for instance using rebase interactive.
- Use history: exercises on how to use the Git history, for instance using blame.


As an individual learner, pick what you want to learn or try out!
As an instructor, you can mix and match exercises: for instance focussing the session on solving common mistakes (Oh Shit, Git!) or on why and how to create a clean Git history (exercises from "Use history" then exercises from "Clean history").

Feel free to suggest new exercises by opening a GitHub [issue](https://github.com/ropensci-training/saperlipopette/issues).

## Recommended resources about Git

For beginners:

- [Happy Git with R](https://happygitwithr.com/)
- [Learn Git branching](https://learngitbranching.js.org/)

For users less new to Git:

- [Git in Practice by Mike McQuaid](https://masalmon.eu/2023/11/01/reading-notes-git-in-practice/)
- [Pro Git by Scott Chacon](https://masalmon.eu/2024/01/19/pro-git-scott-chacon-reading-notes/)