16  Using git

This chapter assumes you have some familiarity with Terminal, Git and Github. Those skills are really independent of R and RStudio, but are being applied here in an R context.

Here are some existing resources that cover those skills, though they are not built to work together … they are written for different contexts and can be redundant.

• Happy Git and Github for the useR is a good resource on how to install and work with Git/Github with RStudio in mind.
• Another option might be to do the first four chapters of Intro to Coding for Journalists. Those lessons were not written with RStudio in mind, but it is a beginner look at Terminal, Git and Github. Once understood, moving that knowledge into RStudio isn’t too much of a stretch.
• Another way to go about it is to start with Github’s Docs. It’s comprehensive, but it’s a lot. There is way more than the basic minimum knowledge there.

But do know that Git needs to already be installed and configured before anyting below works. Once you have that, you can use the Terminal within RStudio to do any Git things you need. There is also a “Git” tab within RStudio where you can interact, though I’m personally less familiar with it.

16.1 Publish to Github Pages

This assumes you already have your repo created and pushed to Github.

16.1.1 Set up the output directory

When you build a Quarto website like we do with our projects, it saves the HTML files into a folder called _site. We’re going to change the _quarto.yml configuration file to instead save those files into a docs/ folder that can then be published (for free) through Github Pages.

1. Open your _quarto.yml file
2. Under the project line (probably at the top) add the output-dir line as described below and save it:

_quarto.yml

project:
  type: website
  output-dir: docs

3. Render all your pages. The best way is to use the Build tab (usually top right) and then click on the Render Website button.
4. Add, commit and push all your changes to git and Github.

This will rework all the files to go into a docs folder. You can remove the _site folder if it had already been created.

Warning

In some instances when making a major change to the _quarto.yml file like this, you might have to restart R and then Render Website to make sure all the changes are understood.

16.1.2 Set up Github Pages

1. Go to your repo in Github.
2. Click on the Settings Tab
3. Click on Pages in the left navigation.
4. Under Build and deployment:
   • Make sure Source is “Deploy from a branch”
   • Set the branch to main and the folder to /docs and click Save.

Github Pages Setup

This will set up a publishing Action and once it has published your files it will add the link to the top of this Pages page. The URL is predictable based on your username and repo name.

Github Pages url

To make updates, make your changes locally, render all the pages, then commit and push them to Github. It takes a couple of minutes for the action to republish pages depending on the size of the site.

16.1.3 Troublshooting Github Pages

The main issue I’ve seen is having a .gitignore file that lists the docs/ folder so that it never gets pushed to Github. That folder has to be in the remote repo for Pages to work with this configuration. Comment or remove that line (or use my .gitignore file listed below)

If you’ve published before already and are pushing corrections, you have to wait on the publishing Action, which can take time (like 5 minutes at most?). Sometimes a browser will hang onto the cache of the earlier page, so try holding down Shift as you refresh the page to make it check the server again.

Beyond that you just have to check the Actions tab in your repo and poke through the logs.

16.2 A good .gitignore file

It’s good practice to have a .gitignore file that excludes things like system files and the like from version control. I usually build them using gitignore.io but there is a setting they use for R that breaks the workflow described above.

I recommend just using a copy of my .gitignore file from this book. It is best to create this file BEFORE YOU START COMMITTING FILES into your repo.

1. Create a new text file called .gitignore. The name of the file is important … it MUST start with a period and MUST NOT have an extension like .txt. It should just be .gitignore.
2. Go the .gitignore file from this book and then copy/paste the contents into your newly-created file. Save and close.

You’ll know the file is named correctly if in your Files pane there is a little red git logo in the file icon.