gist_create_git {gistr} | R Documentation

## Create a gist via git instead of the GitHub Gists HTTP API

### Description

Create a gist via git instead of the GitHub Gists HTTP API

### Usage

    gist_create_git(files = NULL, description = "", public = TRUE,
      browse = TRUE, knit = FALSE, code = NULL, filename = "code.R",
      knitopts = list(), renderopts = list(), include_source = FALSE,
      artifacts = FALSE, imgur_inject = FALSE, git_method = "ssh",
      sleep = 1, ...)

### Arguments

`files` | Files to upload
`description` | (character) Brief description of gist (optional)
`public` | (logical) Whether gist is public (default: TRUE)
`browse` | (logical) To open newly create gist in default browser (default: TRUE)
`knit` | (logical) Knit code before posting as a gist? If the file has a `.Rmd` or `.Rnw` extension, we run the file with `link[knitr]{knit}`, and if it has a `.R` extension, then we use `render`
`code` | Pass in any set of code. This can be a single R object, or many lines of code wrapped in quotes, then curly brackets (see examples below).
`filename` | Name of the file to create, only used if `code` parameter is used. Default to `code.R`
`knitopts, renderopts` | (list) List of variables passed on to `link[knitr]{knit}`, or `render`
`include_source` | (logical) Only applies if `knit=TRUE`. Include source file in the gist in addition to the knitted output.
`artifacts` | (logical/character) Include artifacts or not. If `TRUE`, includes all artifacts. Or you can pass in a file extension to only upload artifacts of certain file exensions. Default: `FALSE`
`imgur_inject` | (logical) Inject `imgur_upload` into your `.Rmd` file to upload files to http://imgur.com/. This will be ignored if the file is a sweave/latex file because the rendered pdf can't be uploaded anyway. Default: FALSE
`git_method` | (character) One of ssh (default) or https. If a remote already exists, we use that remote, and this parameter is ignored.
`sleep` | (integer) Seconds to sleep after creating gist, but before collecting metadata on the gist. If uploading a lot of stuff, you may want to set this to a higher value, otherwise, you may not get accurate metadata for your gist. You can of course always refresh afterwards by calling `gist` with your gist id.
`...` | Further args passed on to `link[httr]{POST}`

### Details

Note that when `browse=TRUE` there is a slight delay in when we open up the gist in your default browser and when the data will display in the gist. We could have this function sleep a while and guess when it will be ready, but instead we open your gist right after we're done sending the data to GitHub. Make sure to refresh the page if you don't see your content right away.

Likewise, the object that is returned from this function call may not have the updated and correct file information. You can retrieve that easily by calling `gist` with the gist id.

This function uses git instead of the HTTP API, and thus requires the R package `git2r`. If you don't have `git2r` installed, and try to use this function, it will stop and tell you to install `git2r`.

This function using git is better suited than `gist_create` for use cases involving:

- Big files - The GitHub API allows only files of up to 1 MB in size. Using git we can get around that limit.

- Binary files - Often artifacts created are binary files like `.png`. The GitHub API doesn't allow transport of binary files, but we can do that with git.

Another difference between this function and `gist_create` is that this function can collect all artifacts coming out of a knit process.

If a gist is somehow deleted, or the remote changes, when you try to push to the same gist again, everything should be fine. We now use `tryCatch` on the push attempt, and if it fails, we'll add a new remote (which means a new gist), and push again.

### See Also

`gist_create`, `gist_create_obj`

### Examples

    ## Not run:
    # prepare a directory and a file
    unlink("~/gitgist", recursive = TRUE)
    dir.create("~/gitgist")
    file <- system.file("examples", "stuff.md", package = "gistr")
    writeLines(readLines(file), con = "~/gitgist/stuff.md")

    # create a gist
    gist_create_git(files = "~/gitgist/stuff.md")

    ## more than one file can be passed in
    unlink("~/gitgist2", recursive = TRUE)
    dir.create("~/gitgist2")
    file.copy(file, "~/gitgist2/")
    cat("hello world", file = "~/gitgist2/hello_world.md")
    list.files("~/gitgist2")
    gist_create_git(c("~/gitgist2/stuff.md", "~/gitgist2/hello_world.md"))

    # Include all files in a directory
    unlink("~/gitgist3", recursive = TRUE)
    dir.create("~/gitgist3")
    cat("foo bar", file="~/gitgist3/foobar.txt")
    cat("hello", file="~/gitgist3/hello.txt")
    list.files("~/gitgist3")
    gist_create_git("~/gitgist3")

    # binary files
    png <- system.file("examples", "file.png", package = "gistr")
    unlink("~/gitgist4", recursive = TRUE)
    dir.create("~/gitgist4")
    file.copy(png, "~/gitgist4/")
    list.files("~/gitgist4")
    gist_create_git(files = "~/gitgist4/file.png")

    # knit files first, then push up
    # note: by default we don't upload images, but you can do that,
    # see next example
    rmd <- system.file("examples", "plots.Rmd", package = "gistr")
    unlink("~/gitgist5", recursive = TRUE)
    dir.create("~/gitgist5")
    file.copy(rmd, "~/gitgist5/")
    list.files("~/gitgist5")
    gist_create_git("~/gitgist5/plots.Rmd", knit = TRUE)

    # collect all/any artifacts from knitting process
    arts <- system.file("examples", "artifacts_eg1.Rmd", package = "gistr")
    unlink("~/gitgist6", recursive = TRUE)
    dir.create("~/gitgist6")
    file.copy(arts, "~/gitgist6/")
    list.files("~/gitgist6")
    gist_create_git("~/gitgist6/artifacts_eg1.Rmd", knit = TRUE,
       artifacts = TRUE)

    # from a code block
    gist_create_git(code={'
    x <- letters
    numbers <- runif(8)
    numbers

    [1] 0.3229318 0.5933054 0.7778408 0.3898947 0.1309717 0.7501378 0.3206379 0.3379005
    '}, filename="my_cool_code.R")

    # Use https instead of ssh
    png <- system.file("examples", "file.png", package = "gistr")
    unlink("~/gitgist7", recursive = TRUE)
    dir.create("~/gitgist7")
    file.copy(png, "~/gitgist7/")
    list.files("~/gitgist7")
    gist_create_git(files = "~/gitgist7/file.png", git_method = "https")

    ## End(Not run)

[Package gistr version 0.4.0 Index]