r-lib/remotes

Install R packages from GitHub, GitLab, Bitbucket, git, svn repositories, URLs

remotes

Install R Packages from remote or local repositories, including GitHub, GitLab, Bitbucket, and Bioconductor

Download and install R packages stored in GitHub, GitLab, Bitbucket, Bioconductor, or plain subversion or git repositories. This package is a lightweight replacement of the install_* functions in devtools. Indeed most of the code was copied over from devtools.

Features

• Installers:
  • Install packages with their dependencies.
  • Install from GitHub, GitLab, Bitbucket.
  • Install from git and subversion repositories.
  • Install from local files or URLs.
  • Install the dependencies of a local package tree.
  • Install specific package versions from CRAN.
• Supports Bioconductor packages.
• Supports the Remotes field in DESCRIPTION. See more in the dependencies vignette.
• Supports the Additional_repositories field in DESCRIPTION.
• Can install itself from GitHub (see below).
• Does not depend on other R packages.
• Does not contain compiled code, so no compiler is needed.
• Does not need any external software (for most of the functionality at least).

Installation

Install the released version of remotes from CRAN:

install.packages("remotes")

Usage

Note that most of the examples here use GitHub. See below for other supported repository types.

To install the latest version of a package in the default branch from GitHub, you can use the user/repo form. Note that user can also be an organization:

remotes::install_github("r-lib/conflicted")

If the R package is inside a subdirectory of the root directory, then give this subdirectory as well:

# build = FALSE because of some specificities of XGBoost package
install_github("dmlc/xgboost/R-package", build = FALSE)

To install a certain branch or commit or tag, append it to the repo name, after an @:

remotes::install_github("gaborcsardi/[email protected]")

To install the latest release, append @*release to the repo name:

remotes::install_github("gaborcsardi/pkgconfig@*release")

To install a pull request, append # and the id (an integer number) of the pull request to the repo name:

remotes::install_github("r-lib/pkgconfig#7")

Dependencies

Dependencies are automatically installed from CRAN. By default, outdated dependencies are automatically upgraded. In interactive sessions you can select a subset of the dependencies to upgrade.

Dependencies on GitHub

It is also possible to install dependencies from GitHub or other supported repositories. For this you need to add a Remotes field to the DESCRIPTION file. Its format is:

Remotes: [remote::]repo_spec, [remote::]repo_spec, ...

where repo_spec is any repository specification the corresponding install_() function can handle. If remote:: is missing, github:: is assumed. Other possible values: gitlab::,bitbucket::, git::, local::, svn::, url::, version::, cran::, bioc::.

See more about the Remotes field in this vignette.

Additional repositories

remotes supports the Additional_repositories field in DESCRIPTION. This is a way to specify dependencies from non-CRAN package repositories. See the Writing R extensions manual for details.

Bioconductor packages

Bioconductor packages are automatically detected and their dependencies are installed from Bioconductor.

Currently supported remote types

• GitHub repositories via install_github.
• Bitbucket repositories via install_bitbucket.
• Generic git repositories via install_git. They need either a system git installation, or the git2r R package.
• Local directories or package archive files via install_local.
• Remote package archive files via install_url.
• Packages in subversion repositories via install_svn. They need a system subversion installation.
• Specific package versions from CRAN or other CRAN-like repositories via install_version. This includes outdated and archived packages as well.
• All dependencies of a package in a local directory via install_deps.

Download methods

• For R older than 3.2, the curl package is required as remotes falls back to curl::curl_download in that case
• For R newer than 3.3, default download.file() method is used. (method = "auto")
• For in between versions,
  • method = "wininet" is used on windows OS
  • method = "libcurl" is used on other OS, if available.

See help("download.file") for information on these methods and for setting proxies if needed.

Standalone mode

remotes will use the curl, git2r and pkgbuild packages if they are installed to provide faster implementations for some aspects of the install process. However if you are using remotes to install or update these packages (or their reverse dependencies) using them during installation may fail (particularly on Windows).

If you set the environment variable R_REMOTES_STANDALONE="true" (e.g. in R Sys.setenv(R_REMOTES_STANDALONE="true")) you can force remotes to operate in standalone mode and use only its internal R implementations. This will allow successful installation of these packages.

Options

remotes uses the following standard R options, see ?options for their details:

• download.file.method for the default download method. See ?download.file.

• pkgType for the package type (source or binary, see manual) to install, download or look up dependencies for.

• repos for the locations of the user’s standard CRAN(-like) repositories.

It also uses some remotes specific options:

• BioC_git for the URL of the default Bioconductor git mirror.

• BioC_mirror for the URL of the Bioconductor mirror.

• unzip for the path of the external unzip program.

Environment variables

• The BITBUCKET_USER and BITBUCKET_PASSWORD environment variables are used for the default Bitbucket user name and password, in install_bitbucket()

• The GITHUB_PAT environment variable is used as the default GitHub personal access token for all GitHub API queries.

• The R_BIOC_MIRROR environment variable can be used to specify an alternative Bioconductor mirror. (The BioC_mirror option takes precedence over this.)

• The R_BIOC_VERSION environment variable can be used to force a Bioconductor version.

• The R_REMOTES_UPGRADE environment variable can be used to set a default preferred value for the upgrade = argument accepted by the various install_*() functions. For example, you can set R_REMOTES_UPGRADE="always" to upgrade dependent packages without asking the user.

• Setting R_REMOTES_STANDALONE="true" forces remotes to work in standalone mode and avoid loading its optional dependencies (curl, git2 and pkgbuild currently. See “Standalone mode” above.

• Setting R_REMOTES_NO_ERRORS_FROM_WARNINGS="false" will cause warning messages during calls to install.packages() to become errors. Often warning messages are caused by dependencies failing to install.

License

GPL (>= 2) © Ascent Digital Services, Posit Software, PBC

remotes's Issues

Merge https://github.com/hadley/devtools/pull/1027

I mean r-lib/devtools#1027

Test cases for new functions (see missing coverage)

Expose remotes:::parse_git_repo

Any chance this could be exposed? I have a couple of use cases for it (building drat repositories mostly, but it's come up a few times). Understand if you want to keep the package super simple though.

Add install_version, maybe

Tests

Package cache

Put it in the user cache.

It can be based on MD5 hashes for CRAN packages, git hashes for git repos. These are the two most important use cases, so it is OK if others do not work.

Use curl_download(mode = "wb")

This makes a difference on Windows, at least for R 3.0.0 and curl 0.5.

I'm trying to provide R 3.0.0 support for r-appveyor, and need to bootstrap devtools somehow.

re #42 (comment)

install_local

Easy

Creation of personal package library does not work

It pops the question, I say y, but then all installations fail. It looks like the directory is not created at all.

ENH: Export github_remote and other remote functions?

Would it be possible to export github_remote? This is the one I'm interested in, but other remotes classes may be relevant. I wanted to use this useful function for a package, but have to use nonexport :::, resulting in warning/note.

I know that it may be unstable (hence the non-export), but I think it may be useful to others to use.

Just download, but don't install

Would be nice.

Add install_bitbucket

Manual

download package on windows behind proxy does not work (easily)

Hi,

Trying to solve this issue with devtools::install_github (r-lib/devtools#1403), I found that remotes package is probably the next thing for some functions in devtools. So I tried it.

However, I encountered an issue as I am on windows and behind a proxy. Trying to install a github package throws an error

remotes::install_github("hadley/lubridate")
#> Error in utils::download.file(url, path, method = download_method(), quiet = quiet,  :  
#> cannot download all files

and even crash R session if proxy is not configured correctly.

This issue is clearly proxy-related.

below is what I have done to make it work. See at the end for Suggestions

About proxy configuration

Proxy configuration is not the easy thing but I managed to deal with it most of the time. Configuring R to Use an HTTP or HTTPS Proxy by RStudio support team helps.

However, the easiest way on windows is to rely on wininet methods which is the default for download.file. see in windows help:

If method = "auto" is chosen (the default), on Windows the "wininet" method is used apart from for ftps:// URLs where "libcurl" is tried. The "wininet" method uses the WinINet functions (part of the OS).

wininet deals with proxy using the 'Internet Option' of the system. And it is used even if libcurl is available (capabilities("libcurl") is TRUE)

In remotes, by default remotes:::download calls remotes:::download_method in which the default is libcurl if it is available. Then, if not, it is wininet

At first, default behavior threw an error. With some efforts I manage to make it work by configuring proxy differently.

• The way describe in Configuring R to Use an HTTP or HTTPS Proxy does not work anymore as it is correct for internal only.
• For libcurl, the form to use is http[s]://[user:password@]machine[:port]. Downloading part of remotes package is now working correctly.
• Forhttr package, I uses set_config and use_proxy to make it work. (Needed for devtools then as it is working with httr) but I think the http_proxy environnement variable is also working

Suggestion

At the end, I found how to deal with the issue. However, I think it could be useful to clarify all this about proxy configuration

• By making wininet the default on windows before testing capabilities("libcurl") in remotes:::download_method
• If libcurl stays the default, by adding some informations in a vignette or in help file to help those behind a proxy. And maybe try to prevent errors or crashes.

What do you think of all this ? I willing to help if you interested as I planned to write something about all this configuration.

Make install_github return names of installed package

Sometimes the name of the github repository does not match the name of the package name in it.

A super useful feature would be if install_github() returns the full name (or path) of the installed package, so that I know what has been installed when using install_github() for programming.

Export everything that devtools exports

Right?

Add install_svn

Skip installation if the sha1 is not changed

Hi,

Is it possible to skip installation if the sha1 is not changed? Currently, devtools::install_github has this feature (https://github.com/hadley/devtools/blob/d8ab190cd05e4bd2a3688a1eab3324109060b111/R/install-remote.R#L26) It would be great if remotes has feature, too.

Thanks,
Wush

Get rid of httr calls

Should install_url() follow redirects?

e.g., install_url('https://github.com/krlmlr/devtools/raw/develop/bin/devtools_1.12.0.9001.zip')

install_github fails on windows for packages requiring compilation

Add install_git

Install script that can be run via source() from online

A'la biocLite.R.

Testing via httrmock

Support tarballs in install_deps()

enters infinite loop on mutual depends in Remotes

Looks like this issue was fixed in the dev version of dplyr, but still impacts this package. e.g. remotes::install_github("hadley/dplyr") fails due to recursive dependency between dplyr and dtplyr,
tidyverse/dplyr#1904.

Thanks!

Accept browser URL in install_github()

Is this where the functionality of devtools::install_github() will land after the diaspora is complete? Or should I open this there?

It would be really nice if a browser URL worked in install_github().

remotes::install_github("https://github.com/juliasilge/southafricastats")
#> Error in username %||% getOption("github.user") %||% stop("Unknown username."): Unknown username.

vs.

remotes::install_github("juliasilge/southafricastats")
#> Using github PAT from envvar GITHUB_PAT
#> Downloading GitHub repo juliasilge/southafricastats@master
#> Installing package into '/Users/jenny/resources/R/library'
#> (as 'lib' is unspecified)

Make sure pkg, pkgs, package, packages arguments of exported functions are consistent

And also compatible with devtools. Although this is not necessarily needed if that would make it inconsistent.

Fix docs

parse_github_repo does not allow trailing slash in subdirectory

A trailing slash in a subdirectory specification causes an error in parse_github_repo

> remotes::parse_github_repo_spec("foo/bar/baz/")
Error in remotes::parse_github_repo_spec("foo/bar/baz/") : 
  Invalid git repo: foo/bar/baz/
> remotes::parse_github_repo_spec("foo/bar/baz")
$username
[1] "foo"

$repo
[1] "bar"

$subdir
[1] "baz"

I think that the these should both point at the same place

Fall back to curl for R < 3.2.0

install-github.me

In the README it says you can install via install-github.me but the code provided is:

source("https://install-github/r-pkgs/remotes")

which when I run it on my machine gives an address could not be resolved error. Changing to

source("https://install-github.me/r-pkgs/remotes")

as implied by the previous line in the readme seems to fix the error. Can you confirm that this is what it should be and modify the README?

WISH: install_*() to return name of package installed

Not all GitHub repositories are named the same way as the R package they install, e.g.

> res <- remotes::install_github("satijalab/seurat")
Using github PAT from envvar GITHUB_PAT
Downloading GitHub repo satijalab/seurat@master
Installing package into '/home/hb/R/x86_64-pc-linux-gnu-library/3.3'
(as 'lib' is unspecified)
* installing *source* package ‘Seurat’ ...
** libs
[...]
*** installing help indices
** building package indices
** testing if installed package can be loaded
* DONE (Seurat)

> res
[1] TRUE

Note, this installs package Seurat (capitalized).

Would it make sense to have the function return the name of the package installed instead of TRUE? (Not sure if remotes ever knows about the package name or not).

Also, and just guessing, but I don't think you can ever get anything else than TRUE returned. For instance, if the repos doesn't exist, you get an error:

> res <- remotes::install_github("satijalab/non_existing_repos")
Using github PAT from envvar GITHUB_PAT
Downloading GitHub repo satijalab/non_existing_repos@master
Error in utils::download.file(url, path, method = download_method(), quiet = quiet,  : 
  cannot download all files

Merge recent install_* changes from devtools

• r-lib/devtools@f4456ef
• r-lib/devtools@3be5877

Do not install (older) version from CRAN if sg is already installed via Remotes

At least I suspect that this happens here:
r-hub/feedback#2 (comment)

CIs

Code coverage

install_url

Seems very easy...

Implement support for gitlab?

Probably as popular now as bitbucket, and has acquired gitorious

Installation with dependencies should first download, then install

I think installation of packages + dependencies should be split in three stages:

1. Download all source packages, including their dependencies
2. Install them in the correct order
3. Apply devtools-specific post-installation steps

For 2., we can leverage install.packages() with a repos argument that points to a local path: All we need to do is to download the packages to some contrib/src/ subdirectory and call tools::write_PACKAGES(). This would finally give us parallel installation with options(Ncpus > 1).

It looks like this would be relatively easy to implement with the current codebase of this repository.

Motivation: remotes does a lot when installing packages and their dependencies, especially if these packages are from different remotes (e.g., CRAN + Bioconductor + GitHub). When revdep-checking RSQLite (with bioconductor = TRUE), I observed twice that I need 2-3 passes to install all revdeps. (The process is single-threaded and takes a day, I'm not too keen to repeat it again.)

Originally filed at r-lib/devtools#1308.

README

Let `install_version` install binary packages from MRAN

Hi,

Is it possible to let the function install_version automatically install the binary packages from MRAN 's historical snapshots of CRAN?

Start using sysreqs

Export install_deps

r-builder uses it

Rewrite install_version to omit available.packages() call

As much as possible.

upgrade=FALSE is not passed through to dependent installations

Upgrading packages tends to lead to really broken sets of packages on windows due to file locking, and so I tend to set upgrade = FALSE quite a lot (I would love a remotes.upgrade global option that I could set to FALSE).

If a package installed by remotes::install_github lists a remote in its description then subsequent installations do not honour the upgrade = FALSE argument

Rename to remotes

remotes:::install_github

Document new functions in README

• svn
• bitbucket
• local
• url
• version
• deps

Installation of Suggested dependencies in drat repositories

aws.s3 is available from a drat repository. I believe it is listed as not available because I am on macOS and it is looking for a binary package, which don't exist for drat repositories.

remotes::install_github("hadley/memoise@e7ccc7e46c3", dependencies = TRUE)
#> ...
#> Skipping 1 packages not available: aws.s3
#> ...

However setting an explicit type of 'source' doesn't work other.

remotes::install_github("hadley/memoise@e7ccc7e46c3", dependencies = TRUE, type = 'source')
#> ...
#> Error in utils::install.packages(...) :
#>  formal argument "type" matched by multiple actual arguments

I had a fix in devtools for a similar issue (r-lib/devtools@efa894f), will try to address it similarly here.

Merge https://github.com/hadley/devtools/pull/903

r-lib/devtools#903