Introducing saperlipopette, a package to practice Git!

I got more confident with Git since reading Git in practice. This has resulted in a more enjoyable Git practice! I’m also more keen to sharing Git “tips” with others, but felt it was challenging to quickly come up with examples to demo some Git workflows. This is what motivated my creating saperlipopette, an R package containing small Git playgrounds to practice various Git commands and strategies!

What is saperlipopette?

The saperlipopette package creates Git messes, or playgrounds, that users need to solve. Part of the exercises are inspired by the wonderful website Oh Shit, Git!?! by Katie Sylor-Miller; others reflect commands that I’ve enjoyed using… or that I’d like to use one day, like git bisect, so the list is partly aspirational!

While saperlipopette itself makes good use of the gert package under the hood, the users can solve the Git messes any way they like, be it with some sort of Git interface, the command line, etc. The package provides no checking of solutions. You get a new folder with a Git mess inside, some tips, and you are the one defining success at the end of one try, by looking at your Git history. Because re-creating an exercise folder only demands your running a function, you can re-create the exercise as needed.

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. You can say “Saperlipopette, Git!”.

How to use saperlipopette?

Setup

You can install the development version of saperlipopette like so:

pak::pak("maelle/saperlipopette")

You’ll also need

• a Git installation, but if you made it here you probably already use Git at least a bit.
• basic Git knowledge, in particular being able to examine the Git history, be it with git log or a tool in your IDE.
• a directory where to store the exercises folder. In all examples we use a temporary directory but if you prefer, you could use a dedicated “scratch directory”.

Basic example

Let’s try the saperlipopette::exo_one_small_change() that goes with “Oh shit, I committed and immediately realized I need to make one small change!".

library("saperlipopette")
parent_path <- withr::local_tempdir()
path <- exo_one_small_change(parent_path)
#> ℹ Follow along in /tmp/RtmpoAeVTm/file152cb747520d9/one-small-change!
# what's in path
fs::dir_tree(path)
#> /tmp/RtmpoAeVTm/file152cb747520d9/one-small-change
#> ├── R
#> └── bla
# with Git in a command line: git log
# or the gert R package
gert::git_log(repo = path)
#> # A tibble: 2 × 6
#>   commit                          author time                files merge message
#> * <chr>                           <chr>  <dttm>              <int> <lgl> <chr>  
#> 1 2ff0d31f566e68ae0ee94b6028a3fa… Jane … 2023-12-15 16:25:00     1 FALSE "feat:…
#> 2 e227ecc55e421f70b6e30602e6a2ee… Jane … 2023-12-15 16:25:00     2 FALSE "First…

At this stage, the user would open the newly created R project and launch an R session, where messages would indicate them what to do, and which URL to follow, to find the corresponding ohshitgit entry if relevant. In practice here the user would change a file, then Git add it, then run git commit --amend --no-edit. The user would examine the Git history before and after this.

#> ✖ "Oh shit, I committed and immediately realized I need to make one small change!"
#> ✖ I wanted to list 3 things in my bla file, not only two!
#> ℹ See <https://ohshitgit.com/#change-last-commit>
#> ℹ For more help use `tip()`

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

tip()
#> • Add 'thing 3' to the bla file and save it.
#> • Add 'bla' file to Git.
#> • `git commit --amend --no-edit`
#> • Examine Git history.

That interface relies on adding an (.gitignored!) .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 could be useful when teaching a group: everyone should be looking at the same hashes on their machine, except for those commits they create themselves.

Feedback welcome!

In this post I introduced the saperlipopette package whose aim is to help users practice their Git skills in a safe (because throw-away) environment! I am very grateful to Jim Gardner for useful feedback and would love to hear from more users, if saperlipopette is of any interest to you.