{"id":13705998,"url":"https://github.com/r-lib/gert","last_synced_at":"2025-04-04T12:08:11.799Z","repository":{"id":44756026,"uuid":"153756760","full_name":"r-lib/gert","owner":"r-lib","description":"Simple git client for R","archived":false,"fork":false,"pushed_at":"2025-03-24T23:35:17.000Z","size":25741,"stargazers_count":154,"open_issues_count":66,"forks_count":34,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-03-28T11:08:56.675Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://docs.ropensci.org/gert/","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/r-lib.png","metadata":{"files":{"readme":"README.md","changelog":"NEWS","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-10-19T09:11:55.000Z","updated_at":"2025-03-24T23:35:20.000Z","dependencies_parsed_at":"2023-02-09T20:46:21.666Z","dependency_job_id":"d565d66b-2a35-4a55-b7a1-0365f8d0ac30","html_url":"https://github.com/r-lib/gert","commit_stats":null,"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r-lib%2Fgert","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r-lib%2Fgert/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r-lib%2Fgert/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r-lib%2Fgert/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/r-lib","download_url":"https://codeload.github.com/r-lib/gert/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247174419,"owners_count":20896078,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-02T22:00:51.080Z","updated_at":"2025-04-04T12:08:11.769Z","avatar_url":"https://github.com/r-lib.png","language":"C","readme":"# gert \u003cimg src=\"man/figures/logo.png\" align=\"right\" alt=\"logo\" width=\"120\" height = \"139\" style = \"border: none; float: right;\"\u003e\n\n*This package is a joint effort from [rOpenSci](https://ropensci.org/) and the [Tidyverse](https://www.tidyverse.org/) team.*\n\n\u003e Simple Git Client for R\n\n\u003c!-- badges: start --\u003e\n[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)\n![runiverse-name](https://ropensci.r-universe.dev/badges/:name)\n![runiverse-package](https://ropensci.r-universe.dev/badges/gert)\n![cran-badge](https://www.r-pkg.org/badges/version/gert)\n[![R-CMD-check](https://github.com/r-lib/gert/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/r-lib/gert/actions/workflows/R-CMD-check.yaml)\n\u003c!-- badges: end --\u003e\n\nSimple git client for R based on 'libgit2' with support for SSH and \nHTTPS remotes. All functions in gert use basic R data types (such as vectors\nand data-frames) for their arguments and return values. User credentials are\nshared with command line 'git' through the git-credential store and ssh keys\nstored on disk or ssh-agent. On Linux, a somewhat recent version of 'libgit2'\nis required; we provide a PPA for older Ubuntu LTS versions.\n\n## Installation\n\n```r\n# To install the latest version\ninstall.packages(\"gert\", repos = c(\n    ropensci = 'https://ropensci.r-universe.dev',\n    CRAN = 'https://cloud.r-project.org'))\n    \n# To install the CRAN release:\ninstall.packages(\"gert\")\n```\n\nOn Linux you need to install libgit2:\n\n - Debian: [libgit2-dev](https://packages.debian.org/buster/libgit2-dev)\n - Fedora / CentOS: [libgit2-devel](https://src.fedoraproject.org/rpms/libgit2)\n - Arch Linux [libgit2](https://archlinux.org/packages/extra/x86_64/libgit2)\n \nIf no suitable version of libgit2 is found, the package automatically tries to download a static build.\n\n\n## Documentation:\n\n - homepage: https://docs.ropensci.org/gert\n - slides: https://jeroen.github.io/gert2019/#1\n\n## Hello world\n\nSome basic commands to get started with gert:\n\n``` r\nlibrary(gert)\nrepo \u003c- git_clone(\"https://github.com/r-lib/gert\")\nsetwd(\"gert\")\n\n# Show some info\ngit_log(max = 10)\n\n# Create a branch\ngit_branch_create(\"mybranch\", checkout = TRUE)\n\n# Commit things\nwriteLines(\"Lorem ipsum dolor sit amet\", 'test.txt')\ngit_add('test.txt')\ngit_commit(\"Adding a file\", author = \"jerry \u003cjerry@gmail.com\u003e\")\ngit_log(max = 10)\n\n# Merge it in master\ngit_branch_checkout(\"master\")\ngit_merge(\"mybranch\")\ngit_branch_delete(\"mybranch\")\n\n# Remove the commit\ngit_reset_hard(\"HEAD^\")\n```\n\n## Should I use HTTPS or SSH remotes?\n\nOn 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:\n\n  - Your credentials are safely stored by your OS, accessible both to gert and command line `git`.\n  - Https works on any network. However the ssh protocol requires port 22, which is often blocked on public wifi networks.\n  - You can authenticate over https using the same GITHUB_PAT that you use for the GitHub API.\n  - libgit2 supports https on all platforms (SSH support depends on libssh2 availability).\n  \nAgain: no need to use your Github master password in gert/git. Instead [generate a personal access token](https://github.com/settings/tokens/new) 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).\n\nNinja 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`.\n\n## Differences with `git2r`\n\nGert is based on [libgit2](https://libgit2.org/), just like the rOpenSci package [git2r](https://docs.ropensci.org/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:\n\n### Simplicity \n\nGert 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.\n\n```\n\u003e gert::git_log(max=6)\n# A tibble: 6 x 6\n  commit                        author                    time                files merge message             \n* \u003cchr\u003e                         \u003cchr\u003e                     \u003cdttm\u003e              \u003cint\u003e \u003clgl\u003e \u003cchr\u003e               \n1 6f39ba6dae890d679970c0f8bf03… Jeroen Ooms \u003cjeroenooms@… 2020-06-16 01:16:33    17 FALSE \"Add some family ta…\n2 c023c407a0f0bfa3955576bc3551… Jeroen Ooms \u003cjeroenooms@… 2020-06-16 01:06:38     1 FALSE \"Check for matching…\n3 24234060ea8e54c73ddd0bce90ff… Jeroen Ooms \u003cjeroenooms@… 2020-06-15 13:17:57     1 FALSE \"Update fedora link…\n4 e60b0fbad129f470a2f7065063fa… Jeroen Ooms \u003cjeroenooms@… 2020-06-15 13:05:45     4 FALSE \"Tweak docs and rea…\n5 629420ddccbab51c1e78f472bf06… Jeroen Ooms \u003cjeroenooms@… 2020-06-15 12:14:25     1 FALSE \"More tests\\n\"      \n6 a62ce14eb887e183ad0a3cf0e22c… Jeroen Ooms \u003cjeroenooms@… 2020-06-15 12:06:41     1 FALSE \"Fix unit test\\n\"   \n```\n\nFor R users who are familiar with the `git` command line, gert should be mostly self-explanatory, and generally \"just work\".\n\n### Automatic authentication\n\nThe 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.\n\nTo 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.\n\nIn gert, authentication is done automatically using the [credentials](https://docs.ropensci.org/credentials/articles/intro.html) 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. \n\nIf 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](https://github.com/jeroen/askpass#readme). Together, these methods should make https authentication \"just work\" in any scenario, without having to manually provide passwords in R.\n\nAuthentication 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):\n\n```r\n\u003e library(gert)\nLinking to libgit2 v1.0.0, ssh support: YES\nGlobal config: /Users/jeroen/.gitconfig\nDefault user: Jeroen Ooms \u003cjeroenooms@gmail.com\n```\n\nOn 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](https://github.com/jeroen/askpass#readme).\nIf the user does not have an SSH key yet, the [credentials](https://docs.ropensci.org/credentials/articles/intro.html) package makes it easy to set that up.\n\n```r\n\u003e library(credentials)\nFound git version 2.24.3 (Apple Git-128)\nSupported HTTPS credential helpers: cache, store\nFound OpenSSH_8.1p1, LibreSSL 2.7.3\nDefault SSH key: /Users/jeroen/.ssh/id_rsa\n```\n\nOne limitation that remains is that libgit2 does not support `ssh-agent` on Windows. This is [unlikely to change](https://github.com/libgit2/libgit2/issues/4958) because ssh-agent uses unix-sockets which do not exist in native Windows software.\n\n### The libgit2 dependency\n\nIf 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.\n\nThe 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.\n\nHowever 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.\n\nWe 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.:\n\n  * [libgit2-dev](https://packages.ubuntu.com/focal/libgit2-dev) on Debian/Ubuntu\n  * [libgit2-devel](https://src.fedoraproject.org/rpms/libgit2) on Fedora\n  * [libgit2](https://archlinux.org/packages/extra/x86_64/libgit2) on Arch Linux\n  * [Homebrew libgit2](https://github.com/Homebrew/homebrew-core/blob/master/Formula/lib/libgit2.rb) on macOS\n  * [rtools40 libgit2](https://github.com/r-windows/rtools-packages/blob/master/mingw-w64-libgit2/PKGBUILD) on Windows\n","funding_links":[],"categories":["C"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fr-lib%2Fgert","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fr-lib%2Fgert","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fr-lib%2Fgert/lists"}