Work with 'GitHub' 'Gists'

Work with 'GitHub' 'gists' from 'R' (e.g., < http://en.wikipedia.org/wiki/GitHub#Gist>, < https://help.github.com/articles/about-gists/>). A 'gist' is simply one or more files with code/text/images/etc. This package allows the user to create new 'gists', update 'gists' with new files, rename files, delete files, get and delete 'gists', star and 'un-star' 'gists', fork 'gists', open a 'gist' in your default browser, get embed code for a 'gist', list 'gist' 'commits', and get rate limit information when 'authenticated'. Some requests require authentication and some do not. 'Gists' website: < https://gist.github.com/>.


Build Status Build status codecov.io rstudio mirror downloads cran version

gistr is a light interface to GitHub's gists for R.

  • rgithub an R client for the Github API by Carlos Scheidegger
  • git2r an R client for the libgit2 C library by Stefan Widgren

Quick start

Install

Stable version from CRAN

install.packages("gistr")

Or dev version from GitHub.

devtools::install_github("ropensci/gistr")
library("gistr")

Authentication

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

  • Generate a personal access token (PAT) at https://help.github.com/articles/creating-an-access-token-for-command-line-use 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.

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):

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:

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)

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

Rate limit information

rate_limit()
#> Rate limit: 5000
#> Remaining:  4938
#> Resets in:  50 minutes

List gists

Limiting to a few results here to keep it brief

gists(per_page = 2)
#> [[1]]
#> <gist>feae4fee7d1debd13e58
#>   URL: https://gist.github.com/feae4fee7d1debd13e58
#>   Description:
#>   Public: TRUE
#>   Created/Edited: 2015-07-03T00:18:51Z / 2015-07-03T00:18:52Z
#>   Files: gistfile1.txt
#>   Truncated?: FALSE
#>
#> [[2]]
#> <gist>03430047a811520d880c
#>   URL: https://gist.github.com/03430047a811520d880c
#>   Description: Bootstrap Customizer Config
#>   Public: TRUE
#>   Created/Edited: 2015-07-03T00:18:30Z / 2015-07-03T00:18:30Z
#>   Files: config.json
#>   Truncated?: FALSE

Since a certain date/time

gists(since='2014-05-26T00:00:00Z', per_page = 2)
#> [[1]]
#> <gist>feae4fee7d1debd13e58
#>   URL: https://gist.github.com/feae4fee7d1debd13e58
#>   Description:
#>   Public: TRUE
#>   Created/Edited: 2015-07-03T00:18:51Z / 2015-07-03T00:18:52Z
#>   Files: gistfile1.txt
#>   Truncated?: FALSE
#>
#> [[2]]
#> <gist>03430047a811520d880c
#>   URL: https://gist.github.com/03430047a811520d880c
#>   Description: Bootstrap Customizer Config
#>   Public: TRUE
#>   Created/Edited: 2015-07-03T00:18:30Z / 2015-07-03T00:18:30Z
#>   Files: config.json
#>   Truncated?: FALSE

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

gists('minepublic', per_page = 2)
#> [[1]]
#> <gist>b15270e69c09f3b87589
#>   URL: https://gist.github.com/b15270e69c09f3b87589
#>   Description: gist gist gist
#>   Public: TRUE
#>   Created/Edited: 2015-07-03T00:10:39Z / 2015-07-03T00:10:39Z
#>   Files: stuff.md
#>   Truncated?: FALSE
#>
#> [[2]]
#> <gist>abbd1a5b0cfc633cfcfd
#>   URL: https://gist.github.com/abbd1a5b0cfc633cfcfd
#>   Description: gist gist gist
#>   Public: TRUE
#>   Created/Edited: 2015-07-03T00:09:34Z / 2015-07-03T00:09:35Z
#>   Files: stuff.md, zoo.json
#>   Truncated?: FALSE, FALSE

List a single commit

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 / 2014-10-15T21:54:29Z
#>   Files: bitly_r.md
#>   Truncated?: FALSE

Create gist

You can pass in files

file <- system.file("examples", "stuff.md", package = "gistr")
gist_create(file, description='a new cool gist', browse = FALSE)
#> <gist>974fd41ff30de9814cc1
#>   URL: https://gist.github.com/974fd41ff30de9814cc1
#>   Description: a new cool gist
#>   Public: TRUE
#>   Created/Edited: 2015-07-03T00:19:18Z / 2015-07-03T00:19:18Z
#>   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.

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
'})
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>4fd5a913e911ad70098c
#>   URL: https://gist.github.com/4fd5a913e911ad70098c
#>   Description:
#>   Public: TRUE
#>   Created/Edited: 2015-07-03T00:19:18Z / 2015-07-03T00:19:18Z
#>   Files: code.R
#>   Truncated?: FALSE

knit and create

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

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

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

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

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

knit a local file

file <- system.file("examples", "stuff.Rmd", package = "gistr")
run(file, knitopts = list(quiet=TRUE)) %>% gist_create(browse = FALSE)
#> <gist>a25bdafc43ee46a98783
#>   URL: https://gist.github.com/a25bdafc43ee46a98783
#>   Description:
#>   Public: TRUE
#>   Created/Edited: 2015-07-03T00:19:19Z / 2015-07-03T00:19:19Z
#>   Files: stuff.md
#>   Truncated?: FALSE

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

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

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

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

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

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

List commits on a gist

gists()[[1]] %>% commits()
#> [[1]]
#> <commit>
#>   Version: 1a418fb4968d550f15f75deb5df4d470f00c6663
#>   User: sckott
#>   Commited: 2015-07-03T00:19:18Z
#>   Commits [total, additions, deletions]: [5,5,0]

Star a gist

Star

gist('7ddb9810fc99c84c65ec') %>% star()
#> <gist>7ddb9810fc99c84c65ec
#>   URL: https://gist.github.com/7ddb9810fc99c84c65ec
#>   Description:
#>   Public: TRUE
#>   Created/Edited: 2014-06-27T17:50:37Z / 2015-07-02T23:56:27Z
#>   Files: code.R, manifest.yml, rrt_manifest.yml
#>   Truncated?: FALSE, FALSE, FALSE

Unstar

gist('7ddb9810fc99c84c65ec') %>% unstar()
#> <gist>7ddb9810fc99c84c65ec
#>   URL: https://gist.github.com/7ddb9810fc99c84c65ec
#>   Description:
#>   Public: TRUE
#>   Created/Edited: 2014-06-27T17:50:37Z / 2015-07-02T23:56:27Z
#>   Files: code.R, manifest.yml, rrt_manifest.yml
#>   Truncated?: FALSE, FALSE, FALSE

Edit a gist

Add files

file <- system.file("examples", "alm.md", package = "gistr")
gists(what = "minepublic")[[1]] %>%
  add_files(file) %>%
  update()
#> <gist>4fd5a913e911ad70098c
#>   URL: https://gist.github.com/4fd5a913e911ad70098c
#>   Description:
#>   Public: TRUE
#>   Created/Edited: 2015-07-03T00:19:18Z / 2015-07-03T00:19:21Z
#>   Files: alm.md, code.R
#>   Truncated?: FALSE, FALSE

Delete files

file <- system.file("examples", "alm.md", package = "gistr")
gists(what = "minepublic")[[1]] %>%
  delete_files(file) %>%
  update()
#> <gist>4fd5a913e911ad70098c
#>   URL: https://gist.github.com/4fd5a913e911ad70098c
#>   Description:
#>   Public: TRUE
#>   Created/Edited: 2015-07-03T00:19:18Z / 2015-07-03T00:19:22Z
#>   Files: code.R
#>   Truncated?: FALSE

Open a gist in your default browser

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

Get embed script

gists()[[1]] %>% embed()
#> [1] "<script src=\"https://gist.github.com/sckott/4fd5a913e911ad70098c.js\"></script>"

List forks

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

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 / 2015-06-11T19:40:48Z
#>   Files:
#>   Truncated?:
#>
#> [[2]]
#> <gist>1643051
#>   URL: https://gist.github.com/1643051
#>   Description: Line Transition (Broken)
#>   Public: TRUE
#>   Created/Edited: 2012-01-19T21:51:30Z / 2015-06-11T19:40:48Z
#>   Files:
#>   Truncated?:

Fork a gist

Returns a gist object

g <- gists()
(forked <- g[[ sample(seq_along(g), 1) ]] %>% fork())
#> <gist>b022baf5c960e864addb
#>   URL: https://gist.github.com/b022baf5c960e864addb
#>   Description: Solution to level 1 in Untrusted: http://alex.nisnevich.com/untrusted/
#>   Public: TRUE
#>   Created/Edited: 2015-07-03T00:19:23Z / 2015-07-03T00:19:23Z
#>   Files: untrusted-lvl1-solution.js
#>   Truncated?: FALSE

Example use case

Working with the Mapzen Pelias geocoding API

The API is described at https://github.com/pelias/pelias, and is still in alpha they say. The steps: get data, make a gist. The data is returned from Mapzen as geojson, so all we have to do is literally push it up to GitHub gists and we're done b/c GitHub renders the map.

library('httr')
base <- "http://pelias.mapzen.com/search"
res <- GET(base, query = list(input = 'coffee shop', lat = 45.5, lon = -122.6))
json <- content(res, as = "text")
gist_create(code = json, filename = "pelias_test.geojson")
#> <gist>017214637bcfeb198070
#>   URL: https://gist.github.com/017214637bcfeb198070
#>   Description:
#>   Public: TRUE
#>   Created/Edited: 2014-10-28T14:42:36Z / 2014-10-28T14:42:36Z
#>   Files: pelias_test.geojson

And here's that gist

pelias img

Meta

  • Please report any issues or bugs.
  • License: MIT
  • Get citation information for gistr in R doing citation(package = 'gistr')
  • Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

rofooter

News

gistr 0.4.0

MINOR IMPROVEMENTS

  • Change all dplyr::rbind_all instances to dplyr::bind_rows (#69)

BUG FIXES

  • Fix to gists() internals for when github.username not set and user selects what = "mineall" - now stops with informative message about setting github.username option (#66) (#67) thanks @sboysel

gistr 0.3.6

MINOR IMPROVEMENTS

  • Added more tests for as.gist()

BUG FIXES

  • Fix to as.gist.list() method to not break sometimes when not all keys returned in JSON content from github API (#63)
  • Fix to update() to work correctly for deleting files. didn't previously set null's correctly (#64)

gistr 0.3.4

NEW FEATURES

  • Gained new function gist_create_git() - creates gists using git instead of the GitHub Gists HTTP API. Uses the package git2r internally to do the git things. (#50) This function has been around a while, but not in the CRAN version, so a few other fixes of note in case you're interested: (#56) (#57) (#58) (#59) (#61)

MINOR IMPROVEMENTS

  • Added new manual file ?create_gists with details of the three different ways to create gists, how they differ, and why there are three different functions to create a gist. (57f13a711fb7a1514caee6a858d4cda31d614e6f)

BUG FIXES

  • Fix to tabl() to give back cleaner data output, returning main metadata for each gist in a single data.frame, then forks and history in separate data.frame's if they exist. Makes for easier understanding and manipulation downstream. (#54)

gistr 0.3.0

NEW FEATURES

  • Gained new function gistr_save() to save gist files to disk easily and optionally open them in your editor/R GUI (#47). In addition, files saved to a directory, with the dir named by the gist id (#49)
  • gist() now accepts either a gist ID or full or partial URL's for a gist (#48)

MINOR IMPROVEMENTS

  • Can now optionally use rmarkdown::render() with gist_create() (#52)
  • Explicitly import non-base R pkg functions, so importing from utils, methods, and stats (#53)
  • Can now toggle use of rmarkdown package with a parameter in gist_create() (#52)
  • Better error messages from the GitHub API (#42)

BUG FIXES

  • Fixed problem with httr v1 where empty list not allowed to pass to the query parameter in GET (#51)

gistr 0.2.0

NEW FEATURES

  • gistr_create() can now optionally include source file if knit=TRUE using the new parameter include_source (#19)
  • new function gist_create_obj() to create a gist directly from a R object, like numeric, list, character, data.frame, matrix (#36) (#44)
  • new function gist_map() to open a full page map in your default browser of a gist after gist creation (#23)
  • new function tabl() (weird function name to avoid the table function in base R). This function goal is to make it easier to play with gist data. Data given back from the GitHub API is great, but is in nested list format (after conversion from JSON) - so is rather hard to manipulate. tabl() makes a data.frame from output of gist(), gists(), as.gist(), and commits() (#25)

MINOR IMPROVEMENTS

  • gistr_create() works with .Rnw files, and example .Rnw file included in the package. (#20)
  • Added ability in gist_create() to optionally include the source file passed into the function call when knit=TRUE (#19)
  • Added ability to inject imgur hooks into a knitted document so that images can be rendered in a gist automatically. The GitHub HTTP API doesn't allow binary uploads (e.g., images), so the parameter imgur_inject uploads your images to imgur and embeds links to the images in your document. (#33)
  • Improved information on truncation. If you request a gist that is larger than 1MB, the returned object says it's truncated. You can download the whole thing using the raw_url, or for larger than 10 MB to the git_pull_url. (#26)

BUG FIXES

  • Fixed unicode problem on Windows (#37)
  • Improved error catching (#28)
  • gist_create() now works for an R script, didn't before (#29)

gistr 0.1.0

NEW FEATURES

  • released to CRAN

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.

install.packages("gistr")

0.4.0 by Scott Chamberlain, a year ago


https://github.com/ropensci/gistr


Report a bug at https://github.com/ropensci/gistr/issues


Browse source code at https://github.com/cran/gistr


Authors: Scott Chamberlain [aut, cre], Ramnath Vaidyanathan [aut], Karthik Ram [aut]


Documentation:   PDF Manual  


Task views: Web Technologies and Services


MIT + file LICENSE license


Imports jsonlite, httr, magrittr, assertthat, knitr, rmarkdown, dplyr

Suggests roxygen2, git2r, testthat


Imported by mapr, pleiades, rbokeh.

Suggested by LDAvis, geojsonio.


See at CRAN