• Stars
    star
    136
  • Rank 252,974 (Top 6 %)
  • Language
    C
  • License
    Other
  • Created over 5 years ago
  • Updated 3 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Simple git client for R

gert logo

This package is a joint effort from rOpenSci and the Tidyverse team.

Simple Git Client for R

Project Status: Active – The project has reached a stable, usable state and is being actively developed. runiverse-name runiverse-package cran-badge R-CMD-check

Simple git client for R based on 'libgit2' with support for SSH and HTTPS remotes. All functions in gert use basic R data types (such as vectors and data-frames) for their arguments and return values. User credentials are shared with command line 'git' through the git-credential store and ssh keys stored on disk or ssh-agent. On Linux, a somewhat recent version of 'libgit2' is required; we provide a PPA for older Ubuntu LTS versions.

Installation

# To install the latest version
install.packages("gert", repos = c(
    ropensci = 'https://ropensci.r-universe.dev',
    CRAN = 'https://cloud.r-project.org'))
    
# To install the CRAN release:
install.packages("gert")

On Linux you need to install libgit2:

If no suitable version of libgit2 is found, the package automatically tries to download a static build.

Documentation:

Hello world

Some basic commands to get started with gert:

library(gert)
repo <- git_clone("https://github.com/r-lib/gert")
setwd("gert")

# Show some info
git_log(max = 10)

# Create a branch
git_branch_create("mybranch", checkout = TRUE)

# Commit things
writeLines("Lorem ipsum dolor sit amet", 'test.txt')
git_add('test.txt')
git_commit("Adding a file", author = "jerry <[email protected]>")
git_log(max = 10)

# Merge it in master
git_branch_checkout("master")
git_merge("mybranch")
git_branch_delete("mybranch")

# Remove the commit
git_reset_hard("HEAD^")

Should I use HTTPS or SSH remotes?

On most platforms, gert supports both HTTPS or SSH remotes. If you don't have any preference, the safest choice is HTTPS remotes using a PAT as the password. This is what I use myself as well. HTTPS remotes have the following benefits:

  • Your credentials are safely stored by your OS, accessible both to gert and command line git.
  • Https works on any network. However the ssh protocol requires port 22, which is often blocked on public wifi networks.
  • You can authenticate over https using the same GITHUB_PAT that you use for the GitHub API.
  • libgit2 supports https on all platforms (SSH support depends on libssh2 availability).

Again: no need to use your Github master password in gert/git. Instead generate a personal access token and enter this as the password when pushing/pulling from https remotes. This works both with gert and with the git command line, even when you have 2FA enabled (which you should).

Ninja tip: use credentials::set_github_pat() to automatically set the GITHUB_PAT environment variable in your R session using the value stored in your git credential store. This is a safer way to store your PAT than hardcoding it in your .Renviron.

Differences with git2r

Gert is based on libgit2, just like the rOpenSci package git2r. Both are good packages. The well established git2r has been on CRAN since 2015, is actively maintained by Stefan Widgren, and is widely used. Gert was started in 2019, and takes a fresh approach based on more recent APIs in libgit2 and lessons learned from using git2r. Some of the main differences:

Simplicity

Gert is focused on high-level functions that shield the end-user from the complexity of libgit2. Functions in gert use standard R data types (such as vectors and data-frames) for their arguments and return values, which should be easy to work with for R users/packages. The target repository is either inferred from current working directory or is specified as a filepath. Branches and remotes are referred to by name, much like command line git. None of the functions in gert expose any externalptr types to the user.

> gert::git_log(max=6)
# A tibble: 6 x 6
  commit                        author                    time                files merge message             
* <chr>                         <chr>                     <dttm>              <int> <lgl> <chr>               
1 6f39ba6dae890d679970c0f8bf03… Jeroen Ooms <jeroenooms@… 2020-06-16 01:16:33    17 FALSE "Add some family ta…
2 c023c407a0f0bfa3955576bc3551… Jeroen Ooms <jeroenooms@… 2020-06-16 01:06:38     1 FALSE "Check for matching…
3 24234060ea8e54c73ddd0bce90ff… Jeroen Ooms <jeroenooms@… 2020-06-15 13:17:57     1 FALSE "Update fedora link…
4 e60b0fbad129f470a2f7065063fa… Jeroen Ooms <jeroenooms@… 2020-06-15 13:05:45     4 FALSE "Tweak docs and rea…
5 629420ddccbab51c1e78f472bf06… Jeroen Ooms <jeroenooms@… 2020-06-15 12:14:25     1 FALSE "More tests\n"      
6 a62ce14eb887e183ad0a3cf0e22c… Jeroen Ooms <jeroenooms@… 2020-06-15 12:06:41     1 FALSE "Fix unit test\n"   

For R users who are familiar with the git command line, gert should be mostly self-explanatory, and generally "just work".

Automatic authentication

The overall goal for auth is that gert should successfully discover credentials whenever that would also be true for command line git. And, should that fail, there is a way to debug it.

To authenticate with a remote in git2r, you often need to manually pass your credentials in every call to, e.g., git2r::clone(). This is always the case for an https remote and is often the case even for an ssh remote. This creates special challenges for those new to git or for indirect use of git2r.

In gert, authentication is done automatically using the credentials package. This package calls out to the local OS credential store which is also used by the git command line. Therefore gert will automatically pick up on https credentials that are safely stored in your OS keychain.

If no credentials are available from the store, gert will try to authenticate using your GITHUB_PAT (if set) for GitHub https remotes. If none of that works, it safely prompts the user for credentials using askpass. Together, these methods should make https authentication "just work" in any scenario, without having to manually provide passwords in R.

Authentication with ssh remotes is a bit more complicated, but gert will again try to make this as smooth as possible. First of all, gert will tell you if SSH is supported when attaching the package (this will be the case on all modern systems):

> library(gert)
Linking to libgit2 v1.0.0, ssh support: YES
Global config: /Users/jeroen/.gitconfig
Default user: Jeroen Ooms <jeroenooms@gmail.com

On Mac/Linux, gert first tries to authenticate using credentials from your ssh-agent. If that doesn't work it will look for a suitable ssh key on your system (usually id_rsa), and if it is protected with a passphrase, gert will safely prompt the user for the passphrase using askpass. If the user does not have an SSH key yet, the credentials package makes it easy to set that up.

> library(credentials)
Found git version 2.24.3 (Apple Git-128)
Supported HTTPS credential helpers: cache, store
Found OpenSSH_8.1p1, LibreSSL 2.7.3
Default SSH key: /Users/jeroen/.ssh/id_rsa

One limitation that remains is that libgit2 does not support ssh-agent on Windows. This is unlikely to change because ssh-agent uses unix-sockets which do not exist in native Windows software.

The libgit2 dependency

If you use Windows or macOS and you install gert from CRAN, it comes with "batteries included". Gert brings in prebuilt versions of external dependencies, like libgit2 and the 3rd party libraries needed to support SSH and TLS (for HTTPS). This approach guarantees that gert uses libraries that are properly configured for your operating system.

The git2r package takes another approach by bundling the libgit2 source code in the R package, and automatically building libgit2 on-the-fly when the R package is compiled. This is mostly for historical reasons, because until recently, libgit2 was not available on every Linux system.

However the problem is that configuring and building libgit2 is complicated (like most system libraries) and requires several platform-specific flags and system dependencies. As a result, git2r is sometimes installed with missing functionality, depending on what was detected during compilation. On macOS for example, some git2r users have SSH support but others do not. Weird problems due to missing libgit2 features turn out to be very persistent, and have caused a lot of frustration. For this reason, gert does not bundle and compile the libgit2 source, but instead always links to system libraries.

We provide prebuilt versions of libgit2 for Windows, MacOS and Linux-x86_64 that are automatically downloaded upon installation. Alternatively on some platforms you can build gert against the system version of libgit2, e.g.:

More Repositories

1

devtools

Tools to make an R developer's life easier
R
2,336
star
2

lintr

Static Code Analysis for R
R
1,135
star
3

httr

httr: a friendly http package for R
R
975
star
4

actions

GitHub Actions for the R community
JavaScript
868
star
5

testthat

An R 📦 to make testing 😀
R
849
star
6

usethis

Set up commonly used 📦 components
R
798
star
7

pkgdown

Generate static html documentation for an R package
R
686
star
8

styler

Non-invasive pretty printing of R code
R
657
star
9

pak

A fresh approach to package installation
C
575
star
10

cli

Tools for making beautiful & useful command line interfaces
R
571
star
11

roxygen2

Generate R package documentation from inline R comments
R
554
star
12

rig

The R Installation Manager
Rust
460
star
13

rlang

Low-level API for programming with R
R
454
star
14

progress

Progress bar in your R terminal
R
447
star
15

R6

Encapsulated object-oriented programming for R
R
393
star
16

here

A simpler way to find your files
R
387
star
17

scales

Tools for ggplot2 scales
R
373
star
18

fs

Provide cross platform file operations based on libuv.
C
353
star
19

covr

Test coverage reports for R
R
328
star
20

rex

Friendly regular expressions for R.
R
325
star
21

crayon

🖍️ R package for colored terminal output — now superseded by cli
R
321
star
22

memoise

Easy memoisation for R
R
310
star
23

remotes

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

lobstr

Understanding complex R objects with tools similar to str()
R
294
star
25

callr

Call R from R
R
281
star
26

vctrs

Generic programming with typed R vectors
C
272
star
27

waldo

Find differences between R objects
R
272
star
28

slider

Sliding Window Functions
R
267
star
29

zeallot

Variable assignment with zeal! (or multiple, unpacking, and destructuring assignment in R)
R
245
star
30

conflicted

An alternative conflict resolution strategy for R
R
242
star
31

bench

High Precision Timing of R Expressions
R
237
star
32

gmailr

Access the Gmail RESTful API from R.
R
234
star
33

processx

Execute and Control Subprocesses from R
R
225
star
34

xml2

Bindings to libxml2
R
212
star
35

asciicast

Turn R scripts into terminal screencasts
R
211
star
36

gh

Minimalistic GitHub API client in R
R
210
star
37

httr2

Make HTTP requests and process their responses. A modern reimagining of httr.
R
206
star
38

cpp11

cpp11 helps you to interact with R objects using C++ code.
C++
187
star
39

keyring

🔐 Access the system credential store from R
R
185
star
40

vdiffr

Visual regression testing and graphical diffing with testthat
C++
177
star
41

svglite

A lightweight svg graphics device for R
C++
177
star
42

pillar

Format columns with colour
R
173
star
43

ragg

Graphic Devices Based on AGG
C++
169
star
44

ymlthis

write YAML for R Markdown, bookdown, blogdown, and more
R
163
star
45

hugodown

Make websites with hugo and RMarkdown
R
163
star
46

withr

Methods For Temporarily Modifying Global State
R
162
star
47

coro

Coroutines for R
R
146
star
48

rprojroot

Finding files in project subdirectories
R
146
star
49

debugme

Easy and efficient debugging for R packages
R
144
star
50

available

Check if a package name is available to use
R
141
star
51

ellipsis

Tools for Working with ...
R
138
star
52

archive

R bindings to libarchive, supporting a large variety of archive formats
C++
138
star
53

later

Schedule an R function or formula to run after a specified period of time.
C++
132
star
54

rray

Simple Arrays
R
130
star
55

isoband

isoband: An R package to generate contour lines and polygons.
C++
130
star
56

fastmap

Fast map implementation for R
C++
128
star
57

prettyunits

Pretty, human readable formatting of quantities
JavaScript
126
star
58

tidyselect

A backend for functions taking tidyverse selections
R
122
star
59

desc

Manipulate DESCRIPTION files
R
120
star
60

gargle

Infrastructure for calling Google APIs from R, including auth
R
112
star
61

rcmdcheck

Run R CMD check from R and collect the results
R
110
star
62

evaluate

A version of eval for R that returns more information about what happened
R
107
star
63

prettycode

Syntax highlight R code in the terminal
R
100
star
64

mockery

A mocking library for R.
R
100
star
65

sloop

S language OOP ⛵️
R
98
star
66

pkgdepends

R Package Dependency Resolution
R
93
star
67

revdepcheck

R package reverse dependency checking
R
93
star
68

clock

A Date-Time Library for R
R
93
star
69

lifecycle

Manage the life cycle of your exported functions and arguments
R
91
star
70

systemfonts

System Native Font Handling in R
C++
90
star
71

gtable

The layout packages that powers ggplot2
R
85
star
72

askpass

Password Entry for R, Git, and SSH
R
83
star
73

rappdirs

Find OS-specific directories to store data, caches, and logs. A port of python's AppDirs
R
81
star
74

zip

Platform independent zip compression via miniz
C
81
star
75

commonmark

High Performance CommonMark and Github Markdown Rendering in R
C
81
star
76

downlit

Syntax Highlighting and Automatic Linking
R
80
star
77

clisymbols

Unicode symbols for CLI applications, with fallbacks
R
74
star
78

tree-sitter-r

C
74
star
79

ps

R package to query, list, manipulate system processes
C
72
star
80

sessioninfo

Print Session Information
R
72
star
81

pkgapi

Create a map of functions for an R package - WORK IN PROGRESS!
R
69
star
82

credentials

Tools for Managing SSH and Git Credentials
R
69
star
83

roxygen2md

Convert elements of roxygen documentation to markdown
R
69
star
84

sodium

R bindings to libsodium
R
68
star
85

backports

Reimplementations of Functions Introduced Since R-3.0.0
R
65
star
86

pkgbuild

Find tools needed to build R packages
R
65
star
87

cliapp

Rich Command Line Applications
R
62
star
88

webfakes

Fake web apps for HTTP testing R packages
C
61
star
89

generics

Common generic methods
R
60
star
90

diffviewer

HTML widget to visually compare files
JavaScript
57
star
91

liteq

Serverless R message queue using SQLite
R
55
star
92

pkgload

Simulate installing and loading a package
R
55
star
93

cachem

Key-value caches for R
R
53
star
94

carrier

Create standalone functions for remote execution
R
49
star
95

brio

Basic R Input Output
R
49
star
96

jose

Javascript Object Signing and Encryption for R
R
47
star
97

urlchecker

Run CRAN URL checks from older versions of R
R
46
star
98

pkgconfig

Private configuration for R packages
R
40
star
99

filelock

Cross platform file locking in R
R
39
star
100

pkginstall

Provides a replacement for `utils::install.packages()`
R
35
star