git and GitHub in R for the casual user

git / GitHub
View source 

If you’ve been taught git and GitHub but practice so rarely that you’re discouraged, what should you do to re-start more easily? Let’s imagine you have to, or really want to, use git and GitHub for your next analysis project. Here’s what I would recommend…

I assume you already own a GitHub account. If not, refer to happygitwithr guidance.

Thanks to the people who shared recommendations on Mastodon, whose names are acknowledged in the rest of the post!

Prepare your tissues…

Or rather your support system. Make sure a collaborator with more git and GitHub practice is on call! If not, remember where you post your R questions. This way if you get stuck somewhere along the line, things will get less desperate.

You might also want to prepare your favorite hot beverage, but you probably won’t be able to read git guidance from tea leaves, hence the need for an actual support plan.

Clear notifications

This step is not completely necessary but could help you for the next re-start. Look at your GitHub notifications! Hopefully you weren’t getting them by email the whole time…

If you see you’ve been getting far too many notifications, tweak the settings!

This way next time you open GitHub, your notifications should have a better signal to noise ratio.

Now if you notice you’ve been missing important notifications, try to either commit to log in more often or get those notifications out of GitHub and into your preferred system. For instance, tell collaborators it’s safer to email you. Another example: maybe don’t watch dplyr repository, but do subscribe to the Tidyverse blog.

Inject a bit of motivation

Why are you doing this anyway? 😅 Good reads are the “Big picture” section of happygitwithr (by Jenny Bryan and collaborators) and the Openscapes GitHub illustrated series by Allison Horst and Julie Lowndes.

Decide whether to use GitHub Desktop

After I first shared my post on Mastodon, several people (Robert M Flight, Steven P Sanderson, Jim Gardner, Francisco Rodriguez-Sanchez) recommended using GitHub Desktop. Its nice interface would, as far as I understand, replace usethis. It’d mean you have R open somewhere, do your thing there, and regularly you do the git/GitHub stuff in the GitHub Desktop interface (setting up a GitHub repository, commits, pushes).

Check your R/GitHub situation

Skip if you use GitHub Desktop (and have installed git!). 😉

In this I assume you have R and RStudio IDE installed. One problem at a time. 😸

Tip by Hao Ye: first setup R so that it loads usethis at each session start, so you might skip writing usethis:: in front of each usethis function.

Let’s see if you have git correctly installed and hooked with GitHub, and remediate if not. Run usethis::git_sitrep(). Also run usethis::gh_token_help().

You might also want to run the whole usethis article about git and gitHub credentials. On Linux, you might need Managing GitHub credentials from R, difficulty level linux by Danielle Navarro.

For git installation, refer to happygitwithr guidance.

Do not be surprised if your tokens expired since the last time you used GitHub from R. Also do not be surprised if it all takes a little while. Take notes on what you’re doing. Next time you might be able to re-start after just running the two sitrep functions!

When re-creating tokens, make sure to give them an informative name (related to the computer you use them for, the project you use them for) as this is very useful for token management. I swear that no longer calling my tokens “mytoken1” has improved my life.

Last but not least, run usethis::git_vaccinate(). It will prevent you leaking credentials, or useless files (.DS_Store), on GitHub.

Run a full cycle

Even if your fantastic analysis project is still waiting for you to finish the mise en place, it might be good to run a full cycle to see whether things work.

Did it work? If not, turn to the docs, a search engine and your support network. If yes, continue!

Initiate your project right

Once you have your project folder set up with create_project() for instance,

  • Initiate git usage with usethis::use_git().
  • Make sure .gitignore is correct: is there for instance a gigantic data file you work with locally but that you do not wish to commit to git, lest it is too heavy for git or GitHub? List it in .gitignore. You can use usethis::use_git_ignore() for that.

Upload your project to GitHub

First, where on GitHub do you want to upload your project?

Your personal account or an organization?

If you wish to upload it to an organization, be aware that it might fail if you don’t have the correct access level. In some GitHub organizations any member can create a repository, in others only owners can. Contact an organization owner if needed.

You might want to create a GitHub organization for your project. Even with a single project in it, the big advantage is that you can better give access to your project to collaborators, with more granularity than for a repository hosted in a personal account.

Private or public?

Do you want your repository to be public or private? Sometimes the choice is obvious, for instance your project is top secret or you really don’t want to share it as is right now. Private repositories have a few less features than public repositories (for instance draft pull requests) depending on your GitHub subscription.

use_github() (or GitHub Desktop)

Now run usethis::use_github(organisation = "your-account-username-or-an-organization", private = TRUE) with the correct arguments. After this you should see your project in a GitHub repository! 🎉

Make commits as you work

Ideally, make a commit everytime you make a substantial, coherent set of changes. To encourage you, you could fill a jar of marbles, one marble per commit?

Realistically, at least make a commit every time you take a break, especially when leaving at the end of your working session.

Push often, each time you make a commit, with the RStudio git tab, the command line or gert::git_push(), or GitHub Desktop.

If you feel icky submitting ugly commits to your pristine repo, think about the idea of branches. With usethis you

With GitHub Desktop you

Keep track of your TODOS

Since you are working on GitHub, you could use the issue tracker of your repository to write down ideas! You can create labels, milestones (so you could procrastinate a lot here 😅).

On Mastodon, Francisco Rodriguez-Sanchez underlined how handy it can be to use GitHub for project management.

Put the “Closed” sign before you leave

Have you done your last commit, last push and opened your last TODO issue? Have you looked over the history of what you did today and earlier in your GitHub repository?

If you intend to leave GitHub for a while,

  • make sure collaborators (or users of your package) have a good idea of how to contact you, and what maintenance is expected (for instance create a file CONTRIBUTING.md where you state the maintenance is stop and go).
  • set a busy status on GitHub.

Procrastinate on your profile

A nice touch would be to make your GitHub profile informative, setting a picture, description, and potentially a GitHub README. If you have GitHub repositories you are proud of, pin them to your profile.

Schedule training sessions?

Your work on checking your git/GitHub situation in RStudio, credentials and such will make your next restart easier. However practice will also help a lot!

Beside trying to get a bit more git into your daily work, you might want to schedule some sessions where you experiment with branches and pull requests in a toy or real repository you own, where you make you first pull request to an external repository. You could run these sessions with other (false) beginners!

Conclusion

First of all, it is awesome you want to use git and GitHub (or GitLab or something else for that matter)! It is not an easy toolset to learn, so no wonder you can get frustated. Hopefully the tips in this post, which I’d summarize as “Remember happygitwithr.com, usethis and/or GitHub Desktop, Openscapes illustrated series; Be patient with yourself”, can help a bit. Good luck!

PS: improve your tooling?