remotes

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

https://github.com/r-lib/remotes

Keywords

Keywords from Contributors

Repository

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

README.Rmd

---
output: github_document
---



```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# remotes

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



[![R-CMD-check](https://github.com/r-lib/remotes/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/r-lib/remotes/actions/workflows/R-CMD-check.yaml)
[![Codecov test coverage](https://codecov.io/gh/r-lib/remotes/branch/main/graph/badge.svg)](https://app.codecov.io/gh/r-lib/remotes?branch=main)
[![CRAN Posit mirror downloads](https://cranlogs.r-pkg.org/badges/remotes)](https://www.r-pkg.org/pkg/remotes)
[![](https://www.r-pkg.org/badges/version/remotes)](https://www.r-pkg.org/pkg/remotes)
[![Lifecycle: stable](https://img.shields.io/badge/lifecycle-stable-brightgreen.svg)](https://lifecycle.r-lib.org/articles/stages.html)


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`](https://github.com/r-lib/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](https://bioconductor.org/) packages.
* Supports the `Remotes` field in `DESCRIPTION`. See more in the
  [dependencies](https://remotes.r-lib.org/articles/dependencies.html) 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:

```r
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:

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

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

```r
# 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 `@`:

```r
remotes::install_github("gaborcsardi/pkgconfig@v2.0.0")
```

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

```r
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:

```r
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](https://remotes.r-lib.org/articles/dependencies.html).

#### 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](https://cran.r-project.org/doc/manuals/r-release/R-exts.html#Package-Dependencies)
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](https://github.com/ropensci/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

Owner

GitHub Events

Committers

Last synced: 12 months ago

Issues and Pull Requests

Last synced: 10 months ago

Packages