Enabling libssh2 for git2r and usethis

Recently, I’ve been on a bit of a usethis binge. I stumbled across usethis::pr_*() set of functions, which is geared toward speeding up contributions to community repositories. There is a wonderful vignette titled “Pull request helpers” that explains their usage in a real-world case study. Unfortunately, a prerequisite for using these commands is to have the repository downloaded. To that end, running usethis::create_from_github() to obtain a local copy of the repository resulted in a dreaded error:

Error in 'git2r_clone': unsupported URL protocol

Underneath the hood, usethis is making a call to git2r’s clone() feature. Unfortunately, this issue has come up before without a satisfactory resolution on macOS.

Having said this, I’ll spend the rest of the post talking about diagnosing the configuration issue and the solution.

Note: This post assumes you have a development toolchain setup and have set the appropriate environment variables for usethis. Before continuing, please make sure to have read through:

Configuration Problem

First, the usethis package provides the git_sitrep() function, which helps diagnose a system’s git configuration. This function reduces the need to type out a lot of unstructured commands in Terminal to figure out what the git situation is.

In my case, the results were:

usethis::git_sitrep()
# Git config (global)
# * Name: 'coatless'
# * Email: 'coatless@notteling.com'
# * Vaccinated: FALSE
# usethis + git2r
# * Default usethis protocol: 'ssh'
# * git2r supports SSH: FALSE
# * Credentials: '<usethis + git2r default behaviour>'
# GitHub
# * Personal access token: '<found in env var>'
# * User: 'coatless'
# * Name: 'coatless'
# * Email(s): 'not-telling'
# Repo
# * Path: '/Users/coatless/Desktop/r/pkg/.git'
# * Local branch -> remote tracking branch: 'master' -> 'origin/master'
# GitHub pull request readiness
# * origin: coatless/pkg, can push

Notice, in this case, the only issue we ran into is:

git2r supports SSH: FALSE

However, that’s what is causing the issue! In fact, it’s a problematic response because it is a silent usethis’s dependency. That is, when usethis is installed so too is git2r. Unfortunately, the CRAN binary version of git2r has libssh2 disabled. As a result, the package binaries from CRAN are problematic.

Binary packages are provided as a convenience. The “binary” aspect means it has been pre-compiled from source code.

So, let’s try to install the package from source locally. Within R, packages can be installed from source by typing:

install.packages('git2r', type = 'source')

Note: This requires that a compiler is present on your system. Please see R Compiler Tools for Rcpp on macOS for help on setting up the developer environment.

Unfortunately, during the package installation, the real issue is made apparent: libssh2 is not installed on the system.

checking for libssh2... no
configure: WARNING:
  ---------------------------------------------
   Unable to find the LibSSH2 library on this
   system. Building a version without support
   for SSH transport.

   To build with SSH support, please install:
     libssh2-1-dev (package on e.g. Debian and Ubuntu)
     libssh2-devel (package on e.g. Fedora, CentOS and RHEL)
     libssh2 (Homebrew package on OS X)
   and try again.

   If the LibSSH2 library is installed on
   your system but the git2r configuration
   is unable to find it, you can specify
   the include and lib path to LibSSH2 with:
   R CMD INSTALL git2r --configure-vars='LIBS=-L/path/to/libs CPPFLAGS=-I/path/to/headers'
  ---------------------------------------------

Solution

Do as the configuration script suggests: Install the libssh2 library via homebrew.

The steps are as follows:

First, open Terminal by going to Applications/Utilities in Finder or typing in mac’s Spotlight search Terminal.

Second, make sure homebrew is installed with:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"

Third, using homebrew, install the libssh2 formula by typing:

brew install libssh2

Fourth, within R type:

install.packages("git2r", 
  type = "source", 
  configure.vars='LIBS=-L/usr/local/Cellar/libssh2/1.9.0_1/lib'
)

This will install the git2r package with the appropriate configuration path to libssh2.

Note: At the time of this writing, the version number is 1.9.0_1. Please replace this version number with the version number of the library installed.

Version information may be obtained by typing into Terminal:

brew list --versions | grep libssh2