Back to vignette index

1 Overview

Help and how-to for certain things we will be using in this class.

2 Github-related

2.1 Set up a github access token

This is necessary for using devtools::install_github() to install private packages, such as your class assignments.

Go into your github account, click settings, and then developer settings:

Select personal access tokens:

Choose to generate a new token:

Generate a new token after naming the token something meaningful and checking the “repo” box:

The result will look something like this. Choose copy link and then paste it somewhere safe.

For example, to install the class R package, you will need the token as follows:

library(devtools)
install_github("agroimpacts/geospaar", build_vignettes = TRUE, 
               auth_token = "the-token-you-just-generated-pasted-here"))

2.2 Branching and merging

A very useful reference for basic branching and merging can be found here

Create a new branch, from within the shell

(replace with a meaningful branch name, e.g. a1)
```
git checkout -b <branchname>
```
Switch branch
- from shell
```
git checkout <branchname>
```
- from within Rstudio

Delete a local branch (if you created one by accident, from shell). Don’t do this to your master branch.
```
git branch -d <branchname>
```
Push a branch to your remote GitHub repo
```
git push origin <branchname>
```
Delete a remote branch
```
git push origin --delete <branchname>
```

Merge two branches

git checkout <branch-you-want-to-merge-onto>
git merge <branch-to-merge-onto-the-branch-you-are-in>

Restore a previous commit

There are multiple ways to do this, some more destructive than others. Perhaps the best way to do this is as follows:
```
git checkout -b <branch-name-for-older-project-state> <commithash>
```
The commit hash is the identifier that git assigns to a particular commit. You can find the hashes under RStudio’s git history dialog in the SHA column. If you want to reset your master branch to the state it was in under this older commit, then one way you could do it that would best preserve your work up that point would be to:
- create a new branch for the current master branch
- delete the files in master branch and commit that change
- merge the older branch back onto master, effectively restoring your master branch to the state it was in at the time of that older commit.
Push all commits to remote

Useful if you have multiple branches with commits that you have not yet pushed to GitHub. This does it all at once:
```
git push --all -u 
```

2.3 RStudio and GitHub

I can push and pull to my repo from the command line, but Rstudio’s git push and pull buttons are greyed out. How do I fix that? The answer can be found here. You can fix this and bring the buttons back to life if you do this, from the shell:
```
git push -u origin <branch-to-push>
```
Note the -u flag. That should fix it.

2.4 Fixing a pandoc error

The current version of geospaar 0.2.4 was built against R 3.6.2 and RStudio 1.2.5033. Older versions of RStudio may cause a pandoc failure when building vignettes. Here is a fix (courtesy of Lei Song). If you get this error:

Run the following lines of code (fix suggested here) from an R script:

# Download pandoc 2.7.1 built with ghc-8.6.4, and instruct
# RStudio + rmarkdown to use it.
local({
  # The directory where Pandoc will be extracted. Feel free
  # to adjust this path as appropriate.
  dir <- "~/rstudio-pandoc"
  # The version of Pandoc to be installed.
  version <- "2.7.1"
  # Create and move to the requested directory.
  dir.create(dir, showWarnings = FALSE, recursive = TRUE)
  owd <- setwd(dir)
  on.exit(setwd(owd), add = TRUE)
  # Construct path to pandoc.
  root <- "https://s3.amazonaws.com/rstudio-buildtools"
  suffix <- sprintf("pandoc-%s-windows-x86_64.zip", version)
  url <- file.path(root, "pandoc-rstudio", version, suffix)
  # Download and extract pandoc.
  file <- basename(url)
  utils::download.file(url, destfile = file)
  utils::unzip(file)
  unlink(file)
  # Write .Renviron to update the version of Pandoc used.
  entry <- paste("RSTUDIO_PANDOC", shQuote(path.expand(dir)), sep = " = ")
  contents <- if (file.exists("~/.Renviron")) readLines("~/.Renviron")
  filtered <- grep("^RSTUDIO_PANDOC", contents, value = TRUE, invert = TRUE)
  amended <- union(filtered, entry)
  writeLines(amended, "~/.Renviron")
  # Report change to the user.
  writeLines("Updated .Renviron:\n")
  writeLines(amended)
  writeLines("\nPlease restart RStudio for these changes to take effect.")
})

Then restart Rstudio and proceed again with devtools::install* steps. This step can be avoided if you update to the latest Rstudio, however.

Help Files

GEOG246-346

2021-08-23

1 Overview