---
title: gistr introduction
author: Scott Chamberlain
date: "2020-07-28"
output: rmarkdown::html_vignette
vignette: >
    %\VignetteIndexEntry{gistr introduction}
    %\VignetteEngine{knitr::rmarkdown}
    %\VignetteEncoding{UTF-8}
---





## Install

Stable version from CRAN



```r
install.packages("gistr")
```

Development version from GitHub



```r
remotes::install_github("ropensci/gistr")
```



```r
library("gistr")
```

## Authentication

There are two ways to authorise gistr to work with your GitHub account:

* Generate a personal access token (PAT) **with the gist scope selected** at [https://help.github.com/articles/creating-an-access-token-for-command-line-use](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) and record it in the `GITHUB_PAT` environment variable.
  - To test out this approach, execute this in R: `Sys.setenv(GITHUB_PAT = "blahblahblah")`, where "blahblahblah" is the PAT you got from GitHub. Then take `gistr` out for a test drive.
  - If that works, you will probably want to define the GITHUB_PAT environment variable in a file such as `~/.bash_profile` or `~/.Renviron`.
* Interactively login into your GitHub account and authorise with OAuth.

Using the PAT is recommended.

Using the `gist_auth()` function you can authenticate separately first, or if you're not authenticated, this function will run internally with each function call. If you have a PAT, that will be used, if not, OAuth will be used.


```r
gist_auth()
```

## Workflow

In `gistr` you can use pipes, introduced perhaps first in R in the package `magrittr`, to pass outputs from one function to another. If you have used `dplyr` with pipes you can see the difference, and perhaps the utility, of this workflow over the traditional workflow in R. You can use a non-piping or a piping workflow with `gistr`. Examples below use a mix of both workflows. Here is an example of a piping workflow (with some explanation):


```r
file <- system.file("examples", "alm.md", package = "gistr")
gists(what = "minepublic")[[1]] %>% # List my public gists, and index to get just the 1st one
  add_files(file) %>% # Add a new file to that gist
  update() # update sends a PATCH command to the Gists API to add the file to your gist online
```

And a non-piping workflow that does the same exact thing:


```r
file <- system.file("examples", "alm.md", package = "gistr")
g <- gists(what = "minepublic")[[1]]
g <- add_files(g, file)
update(g)
```

Or you could string them all together in one line (but it's rather difficult to follow what's going on because you have to read from the inside out)


```r
file <- system.file("examples", "alm.md", package = "gistr")
update(add_files(gists(what = "minepublic")[[1]], file))
```

## Rate limit information


```r
rate_limit()
#> Rate limit: 5000
#> Remaining:  4998
#> Resets in:  59 minutes
```

## List gists

Limiting to a few results here to keep it brief


```r
gists(per_page = 2)
#> [[1]]
#> <gist>721a433293af4cb1fb0f66d7ccb37339
#>   URL: https://gist.github.com/721a433293af4cb1fb0f66d7ccb37339
#>   Description: Atividades 8o Ano
#>   Public: TRUE
#>   Created/Edited: 2020-07-28T20:18:22Z / 2020-07-28T20:18:23Z
#>   Files: 8o_ano.md
#>   Truncated?: FALSE
#> 
#> [[2]]
#> <gist>d1064ad4f7fa9cd30b4409ade98fbd92
#>   URL: https://gist.github.com/d1064ad4f7fa9cd30b4409ade98fbd92
#>   Description: Averdonk Groessen
#>   Public: TRUE
#>   Created/Edited: 2020-07-28T20:18:11Z / 2020-07-28T20:18:11Z
#>   Files: averdonk-groessen.markdown, index.pug, script.js, scripts, style.sass, styles
#>   Truncated?: FALSE, FALSE, FALSE, FALSE, FALSE, FALSE
```

Since a certain date/time


```r
gists(since='2014-05-26T00:00:00Z', per_page = 2)
#> [[1]]
#> <gist>721a433293af4cb1fb0f66d7ccb37339
#>   URL: https://gist.github.com/721a433293af4cb1fb0f66d7ccb37339
#>   Description: Atividades 8o Ano
#>   Public: TRUE
#>   Created/Edited: 2020-07-28T20:18:22Z / 2020-07-28T20:18:23Z
#>   Files: 8o_ano.md
#>   Truncated?: FALSE
#> 
#> [[2]]
#> <gist>d1064ad4f7fa9cd30b4409ade98fbd92
#>   URL: https://gist.github.com/d1064ad4f7fa9cd30b4409ade98fbd92
#>   Description: Averdonk Groessen
#>   Public: TRUE
#>   Created/Edited: 2020-07-28T20:18:11Z / 2020-07-28T20:18:11Z
#>   Files: averdonk-groessen.markdown, index.pug, script.js, scripts, style.sass, styles
#>   Truncated?: FALSE, FALSE, FALSE, FALSE, FALSE, FALSE
```

Request different types of gists, one of public, minepublic, mineall, or starred.


```r
gists('minepublic', per_page = 2)
#> [[1]]
#> <gist>792675323dea1961ce038b2e051d66d4
#>   URL: https://gist.github.com/792675323dea1961ce038b2e051d66d4
#>   Description: 
#>   Public: TRUE
#>   Created/Edited: 2020-07-28T20:17:34Z / 2020-07-28T20:17:42Z
#>   Files: code.R
#>   Truncated?: FALSE
#> 
#> [[2]]
#> <gist>98badbaf7334a8a5707418543e178901
#>   URL: https://gist.github.com/98badbaf7334a8a5707418543e178901
#>   Description: a new cool gist
#>   Public: TRUE
#>   Created/Edited: 2020-07-28T20:17:33Z / 2020-07-28T20:17:33Z
#>   Files: stuff.md
#>   Truncated?: FALSE
```


## List a single commit


```r
gist(id = 'f1403260eb92f5dfa7e1')
#> <gist>f1403260eb92f5dfa7e1
#>   URL: https://gist.github.com/f1403260eb92f5dfa7e1
#>   Description: Querying bitly from R 
#>   Public: TRUE
#>   Created/Edited: 2014-10-15T20:40:12Z / 2015-08-29T14:07:43Z
#>   Files: bitly_r.md
#>   Truncated?: FALSE
```

## Create gist

You can pass in files


```r
file <- system.file("examples", "stuff.md", package = "gistr")
gist_create(file, description='a new cool gist', browse = FALSE)
#> <gist>f7aa5e70e2fb40f4d92e972bcfa6224f
#>   URL: https://gist.github.com/f7aa5e70e2fb40f4d92e972bcfa6224f
#>   Description: a new cool gist
#>   Public: TRUE
#>   Created/Edited: 2020-07-28T20:18:27Z / 2020-07-28T20:18:27Z
#>   Files: stuff.md
#>   Truncated?: FALSE
```

Or, wrap `gist_create()` around some code in your R session/IDE, with just the function name, and a `{'` at the start and a `}'` at the end.


```r
gist_create(code={'
x <- letters
numbers <- runif(8)
numbers

[1] 0.3229318 0.5933054 0.7778408 0.3898947 0.1309717 0.7501378 0.3206379 0.3379005
'})
```


```r
gist_create(code={'
x <- letters
numbers <- runif(8)
numbers

[1] 0.3229318 0.5933054 0.7778408 0.3898947 0.1309717 0.7501378 0.3206379 0.3379005
'}, browse=FALSE)
#> <gist>394103ff248f2be67bbccce863a89ca7
#>   URL: https://gist.github.com/394103ff248f2be67bbccce863a89ca7
#>   Description: 
#>   Public: TRUE
#>   Created/Edited: 2020-07-28T20:18:29Z / 2020-07-28T20:18:29Z
#>   Files: code.R
#>   Truncated?: FALSE
```

### knit and create

You can also knit an input file before posting as a gist:


```r
file <- system.file("examples", "stuff.Rmd", package = "gistr")
gist_create(file, description='a new cool gist', knit=TRUE)
#> <gist>4162b9c53479fbc298db
#>   URL: https://gist.github.com/4162b9c53479fbc298db
#>   Description: a new cool gist
#>   Public: TRUE
#>   Created/Edited: 2014-10-27T16:07:31Z / 2014-10-27T16:07:31Z
#>   Files: stuff.md
#>   Truncated?: FALSE
```

Or code blocks before (note that code blocks without knitr block demarcations will result in unexecuted code):


```r
gist_create(code={'
x <- letters
(numbers <- runif(8))
'}, knit=TRUE)
#> <gist>ec45c396dee4aa492139
#>   URL: https://gist.github.com/ec45c396dee4aa492139
#>   Description:
#>   Public: TRUE
#>   Created/Edited: 2014-10-27T16:09:09Z / 2014-10-27T16:09:09Z
#>   Files: file81720d1ceff.md
#>   Truncated?: FALSE
```

## knit code from file path, code block, or gist file

knit a local file


```r
file <- system.file("examples", "stuff.Rmd", package = "gistr")
run(file, knitopts = list(quiet=TRUE)) %>% gist_create(browse = FALSE)
#> <gist>ceeddf11ebf775a1fe465f6791e15323
#>   URL: https://gist.github.com/ceeddf11ebf775a1fe465f6791e15323
#>   Description: 
#>   Public: TRUE
#>   Created/Edited: 2020-07-28T20:18:31Z / 2020-07-28T20:18:31Z
#>   Files: stuff.md
#>   Truncated?: FALSE
```



knit a code block (knitr code block notation missing, do add that in) (result not shown)


```r
run({'
x <- letters
(numbers <- runif(8))
'}) %>% gist_create
```

knit a file from a gist, has to get file first (result not shown)


```r
gists('minepublic')[[1]] %>% run() %>% update()
```

## working with images

The GitHub API doesn't let you upload binary files (e.g., images) via their HTTP API, which we use in `gistr`. There is a workaround.

If you are using `.Rmd` or `.Rnw` files, you can set `imgur_inject = TRUE` in `gistr_create()` so that imgur knit options are injected at the top of your file so that images will be uploaded to imgur. Alternatively, you can do this yourself, setting knit options to use imgur.

A file already using imgur


```r
file <- system.file("examples", "plots_imgur.Rmd", package = "gistr")
gist_create(file, knit=TRUE)
#> <gist>1a6e7f7d6ddb739fce0b
#>   URL: https://gist.github.com/1a6e7f7d6ddb739fce0b
#>   Description:
#>   Public: TRUE
#>   Created/Edited: 2015-03-19T00:20:48Z / 2015-03-19T00:20:48Z
#>   Files: plots_imgur.md
```

A file _NOT_ already using imgur


```r
file <- system.file("examples", "plots.Rmd", package = "gistr")
gist_create(file, knit=TRUE, imgur_inject = TRUE)
#> <gist>ec9987ad245bbc668c72
#>   URL: https://gist.github.com/ec9987ad245bbc668c72
#>   Description:
#>   Public: TRUE
#>   Created/Edited: 2015-03-19T00:21:13Z / 2015-03-19T00:21:13Z
#>   Files: plots.md
#>   Truncated?: FALSE
```

## List commits on a gist


```r
gists()[[1]] %>% commits()
#> [[1]]
#> <commit>
#>   Version: b640145362bb2272c5f0a06ae2aee3241b8f6f59
#>   User: sckott
#>   Commited: 2020-07-28T20:18:28Z
#>   Commits [total, additions, deletions]: [5,5,0]
```

## Star a gist

Star


```r
gist('cbb0507082bb18ff7e4b') %>% star()
#> <gist>cbb0507082bb18ff7e4b
#>   URL: https://gist.github.com/cbb0507082bb18ff7e4b
#>   Description: This is my technical interview cheat sheet.  Feel free to fork it or do whatever you want with it.  PLEASE let me know if there are any errors or if anything crucial is missing.  I will add more links soon.
#>   Public: TRUE
#>   Created/Edited: 2014-05-02T19:43:13Z / 2018-04-16T21:11:53Z
#>   Files: The Technical Interview Cheat Sheet.md
#>   Truncated?: FALSE
```

Unstar


```r
gist('cbb0507082bb18ff7e4b') %>% unstar()
#> <gist>cbb0507082bb18ff7e4b
#>   URL: https://gist.github.com/cbb0507082bb18ff7e4b
#>   Description: This is my technical interview cheat sheet.  Feel free to fork it or do whatever you want with it.  PLEASE let me know if there are any errors or if anything crucial is missing.  I will add more links soon.
#>   Public: TRUE
#>   Created/Edited: 2014-05-02T19:43:13Z / 2018-04-16T21:27:36Z
#>   Files: The Technical Interview Cheat Sheet.md
#>   Truncated?: FALSE
```

## Edit a gist

Add files


```r
file <- system.file("examples", "alm.md", package = "gistr")
gists(what = "minepublic")[[1]] %>%
  add_files(file) %>%
  update()
#> <gist>394103ff248f2be67bbccce863a89ca7
#>   URL: https://gist.github.com/394103ff248f2be67bbccce863a89ca7
#>   Description: 
#>   Public: TRUE
#>   Created/Edited: 2020-07-28T20:18:29Z / 2020-07-28T20:18:34Z
#>   Files: alm.md, code.R
#>   Truncated?: FALSE, FALSE
```

Delete files


```r
file <- system.file("examples", "alm.md", package = "gistr")
gists(what = "minepublic")[[1]] %>%
  delete_files(file) %>%
  update()
#> <gist>394103ff248f2be67bbccce863a89ca7
#>   URL: https://gist.github.com/394103ff248f2be67bbccce863a89ca7
#>   Description: 
#>   Public: TRUE
#>   Created/Edited: 2020-07-28T20:18:29Z / 2020-07-28T20:18:36Z
#>   Files: code.R
#>   Truncated?: FALSE
```

## Open a gist in your default browser


```r
gists()[[1]] %>% browse()
```

> Opens the gist in your default browser

## Get embed script


```r
gists()[[1]] %>% embed()
#> [1] "<script src=\"https://gist.github.com/anupamgogoi-wso2/9230e4ade0074320ec95992ba2fbf518.js\"></script>"
```

## List forks

Returns a list of `gist` objects, just like `gists()`


```r
gist(id='1642874') %>% forks(per_page=2)
#> [[1]]
#> <gist>1642989
#>   URL: https://gist.github.com/1642989
#>   Description: Spline Transition
#>   Public: TRUE
#>   Created/Edited: 2012-01-19T21:45:20Z / 2019-10-23T20:09:07Z
#>   Files: 
#>   Truncated?: 
#> 
#> [[2]]
#> <gist>1643051
#>   URL: https://gist.github.com/1643051
#>   Description: Line Transition (Broken)
#>   Public: TRUE
#>   Created/Edited: 2012-01-19T21:51:30Z / 2019-10-23T20:08:44Z
#>   Files: 
#>   Truncated?:
```

## Fork a gist

Returns a `gist` object


```r
g <- gists()
(forked <- g[[ sample(seq_along(g), 1) ]] %>% fork())
#> <gist>72a9327aac0cab09900b04a027069ae5
#>   URL: https://gist.github.com/72a9327aac0cab09900b04a027069ae5
#>   Description: Rimworld output log published using HugsLib
#>   Public: TRUE
#>   Created/Edited: 2020-07-28T20:18:43Z / 2020-07-28T20:18:43Z
#>   Files: output_log.txt
#>   Truncated?: FALSE
```





## Example use cases

_Round-trip storage of a data frame_

Maybe you want to use a gist to share some data as an alternative to `dput`? We can do this by writing our `data.frame` to a temporary buffer and passing it to `gist_create`. We can read the data back from the gist by passing its content to `read.csv`.



```r
data(iris)

str <- ''
tc  <- textConnection('str', 'w', local = TRUE)
write.csv(iris, file = tc, row.names = FALSE)
close(tc)

content <- list(content=paste(as.character(str), collapse='\n'))

gistr::gist_create(code = {
  content$content
}, description = "using a gist as a data store", 
filename = "iris.csv")
#> <gist>c7dfe593f4944df4818df884689734f9
#>   URL: https://gist.github.com/c7dfe593f4944df4818df884689734f9
#>   Description: using a gist as a data store
#>   Public: TRUE
#>   Created/Edited: 2019-07-18T14:23:23Z / 2019-07-18T14:23:23Z
#>   Files: iris.csv
#>   Truncated?: FALSE

output <- read.csv(
  text = gist(gists(what = "minepublic", per_page = 1)[[1]]$id)$
    files$iris.csv$content)

identical(output, iris)
#> TRUE
```