1libgit2 - the Git linkable library 2================================== 3 4| Build Status | | 5| ------------ | - | 6| **main** branch CI builds | [![CI Build](https://github.com/libgit2/libgit2/workflows/CI%20Build/badge.svg?event=push)](https://github.com/libgit2/libgit2/actions?query=workflow%3A%22CI+Build%22+event%3Apush) | 7| **v1.2 branch** CI builds | [![CI Build](https://github.com/libgit2/libgit2/workflows/CI%20Build/badge.svg?branch=maint%2Fv1.2&event=push)](https://github.com/libgit2/libgit2/actions?query=workflow%3A%22CI+Build%22+event%3Apush+branch%3Amaint%2Fv1.2) | 8| **v1.1 branch** CI builds | [![CI Build](https://github.com/libgit2/libgit2/workflows/CI%20Build/badge.svg?branch=maint%2Fv1.1&event=push)](https://github.com/libgit2/libgit2/actions?query=workflow%3A%22CI+Build%22+event%3Apush+branch%3Amaint%2Fv1.1) | 9| **Nightly** builds | [![Nightly Build](https://github.com/libgit2/libgit2/workflows/Nightly%20Build/badge.svg)](https://github.com/libgit2/libgit2/actions?query=workflow%3A%22Nightly+Build%22) [![Coverity Scan Status](https://scan.coverity.com/projects/639/badge.svg)](https://scan.coverity.com/projects/639) | 10 11`libgit2` is a portable, pure C implementation of the Git core methods 12provided as a linkable library with a solid API, allowing to build Git 13functionality into your application. Language bindings like 14[Rugged](https://github.com/libgit2/rugged) (Ruby), 15[LibGit2Sharp](https://github.com/libgit2/libgit2sharp) (.NET), 16[pygit2](http://www.pygit2.org/) (Python) and 17[NodeGit](http://nodegit.org) (Node) allow you to build Git tooling 18in your favorite language. 19 20`libgit2` is used to power Git GUI clients like 21[GitKraken](https://gitkraken.com/) and [gmaster](https://gmaster.io/) 22and on Git hosting providers like [GitHub](https://github.com/), 23[GitLab](https://gitlab.com/) and 24[Azure DevOps](https://azure.com/devops). 25We perform the merge every time you click "merge pull request". 26 27`libgit2` is licensed under a **very permissive license** (GPLv2 with a special 28Linking Exception). This basically means that you can link it (unmodified) 29with any kind of software without having to release its source code. 30Additionally, the example code has been released to the public domain (see the 31[separate license](examples/COPYING) for more information). 32 33Table of Contents 34================= 35 36* [Using libgit2](#using-libgit2) 37* [Quick Start](#quick-start) 38* [Getting Help](#getting-help) 39* [What It Can Do](#what-it-can-do) 40* [Optional dependencies](#optional-dependencies) 41* [Initialization](#initialization) 42* [Threading](#threading) 43* [Conventions](#conventions) 44* [Building libgit2 - Using CMake](#building-libgit2---using-cmake) 45 * [Building](#building) 46 * [Installation](#installation) 47 * [Advanced Usage](#advanced-usage) 48 * [Compiler and linker options](#compiler-and-linker-options) 49 * [MacOS X](#macos-x) 50 * [Android](#android) 51 * [MinGW](#mingw) 52* [Language Bindings](#language-bindings) 53* [How Can I Contribute?](#how-can-i-contribute) 54* [License](#license) 55 56Using libgit2 57============= 58 59Most of these instructions assume that you're writing an application 60in C and want to use libgit2 directly. If you're _not_ using C, 61and you're writing in a different language or platform like .NET, 62Node.js, or Ruby, then there is probably a 63"[language binding](#language-bindings)" that you can use to take care 64of the messy tasks of calling into native code. 65 66But if you _do_ want to use libgit2 directly - because you're building 67an application in C - then you may be able use an existing binary. 68There are packages for the 69[vcpkg](https://github.com/Microsoft/vcpkg) and 70[conan](https://conan.io/center/libgit2) 71package managers. And libgit2 is available in 72[Homebrew](https://formulae.brew.sh/formula/libgit2) and most Linux 73distributions. 74 75However, these versions _may_ be outdated and we recommend using the 76latest version if possible. Thankfully libgit2 is not hard to compile. 77 78Quick Start 79=========== 80 81**Prerequisites** for building libgit2: 82 831. [CMake](https://cmake.org/), and is recommended to be installed into 84 your `PATH`. 852. [Python](https://www.python.org) is used by our test framework, and 86 should be installed into your `PATH`. 873. C compiler: libgit2 is C90 and should compile on most compilers. 88 * Windows: Visual Studio is recommended 89 * Mac: Xcode is recommended 90 * Unix: gcc or clang is recommended. 91 92**Build** 93 941. Create a build directory beneath the libgit2 source directory, and change 95 into it: `mkdir build && cd build` 962. Create the cmake build environment: `cmake ..` 973. Build libgit2: `cmake --build .` 98 99Trouble with these steps? Read our [troubleshooting guide](docs/troubleshooting.md). 100More detailed build guidance is available below. 101 102Getting Help 103============ 104 105**Chat with us** 106 107- via IRC: join [#libgit2](https://web.libera.chat/#libgit2) on 108 [libera](https://libera.chat). 109- via Slack: visit [slack.libgit2.org](http://slack.libgit2.org/) to sign up, 110 then join us in `#libgit2` 111 112**Getting Help** 113 114If you have questions about the library, please be sure to check out the 115[API documentation](http://libgit2.github.com/libgit2/). If you still have 116questions, reach out to us on Slack or post a question on 117[StackOverflow](http://stackoverflow.com/questions/tagged/libgit2) (with the `libgit2` tag). 118 119**Reporting Bugs** 120 121Please open a [GitHub Issue](https://github.com/libgit2/libgit2/issues) and 122include as much information as possible. If possible, provide sample code 123that illustrates the problem you're seeing. If you're seeing a bug only 124on a specific repository, please provide a link to it if possible. 125 126We ask that you not open a GitHub Issue for help, only for bug reports. 127 128**Reporting Security Issues** 129 130Please have a look at SECURITY.md. 131 132What It Can Do 133============== 134 135libgit2 provides you with the ability to manage Git repositories in the 136programming language of your choice. It's used in production to power many 137applications including GitHub.com, Plastic SCM and Azure DevOps. 138 139It does not aim to replace the git tool or its user-facing commands. Some APIs 140resemble the plumbing commands as those align closely with the concepts of the 141Git system, but most commands a user would type are out of scope for this 142library to implement directly. 143 144The library provides: 145 146* SHA conversions, formatting and shortening 147* abstracted ODB backend system 148* commit, tag, tree and blob parsing, editing, and write-back 149* tree traversal 150* revision walking 151* index file (staging area) manipulation 152* reference management (including packed references) 153* config file management 154* high level repository management 155* thread safety and reentrancy 156* descriptive and detailed error messages 157* ...and more (over 175 different API calls) 158 159As libgit2 is purely a consumer of the Git system, we have to 160adjust to changes made upstream. This has two major consequences: 161 162* Some changes may require us to change provided interfaces. While we try to 163 implement functions in a generic way so that no future changes are required, 164 we cannot promise a completely stable API. 165* As we have to keep up with changes in behavior made upstream, we may lag 166 behind in some areas. We usually to document these incompatibilities in our 167 issue tracker with the label "git change". 168 169Optional dependencies 170===================== 171 172While the library provides git functionality without the need for 173dependencies, it can make use of a few libraries to add to it: 174 175- pthreads (non-Windows) to enable threadsafe access as well as multi-threaded pack generation 176- OpenSSL (non-Windows) to talk over HTTPS and provide the SHA-1 functions 177- LibSSH2 to enable the SSH transport 178- iconv (OSX) to handle the HFS+ path encoding peculiarities 179 180Initialization 181=============== 182 183The library needs to keep track of some global state. Call 184 185 git_libgit2_init(); 186 187before calling any other libgit2 functions. You can call this function many times. A matching number of calls to 188 189 git_libgit2_shutdown(); 190 191will free the resources. Note that if you have worker threads, you should 192call `git_libgit2_shutdown` *after* those threads have exited. If you 193require assistance coordinating this, simply have the worker threads call 194`git_libgit2_init` at startup and `git_libgit2_shutdown` at shutdown. 195 196Threading 197========= 198 199See [threading](docs/threading.md) for information 200 201Conventions 202=========== 203 204See [conventions](docs/conventions.md) for an overview of the external 205and internal API/coding conventions we use. 206 207Building libgit2 - Using CMake 208============================== 209 210Building 211-------- 212 213`libgit2` builds cleanly on most platforms without any external dependencies. 214Under Unix-like systems, like Linux, \*BSD and Mac OS X, libgit2 expects `pthreads` to be available; 215they should be installed by default on all systems. Under Windows, libgit2 uses the native Windows API 216for threading. 217 218The `libgit2` library is built using [CMake](<https://cmake.org/>) (version 2.8 or newer) on all platforms. 219 220On most systems you can build the library using the following commands 221 222 $ mkdir build && cd build 223 $ cmake .. 224 $ cmake --build . 225 226Alternatively you can point the CMake GUI tool to the CMakeLists.txt file and generate platform specific build project or IDE workspace. 227 228If you're not familiar with CMake, [a more detailed explanation](https://preshing.com/20170511/how-to-build-a-cmake-based-project/) may be helpful. 229 230Running Tests 231------------- 232 233Once built, you can run the tests from the `build` directory with the command 234 235 $ ctest -V 236 237Alternatively you can run the test suite directly using, 238 239 $ ./libgit2_clar 240 241Invoking the test suite directly is useful because it allows you to execute 242individual tests, or groups of tests using the `-s` flag. For example, to 243run the index tests: 244 245 $ ./libgit2_clar -sindex 246 247To run a single test named `index::racy::diff`, which corresponds to the test 248function [`test_index_racy__diff`](https://github.com/libgit2/libgit2/blob/main/tests/index/racy.c#L23): 249 250 $ ./libgit2_clar -sindex::racy::diff 251 252The test suite will print a `.` for every passing test, and an `F` for any 253failing test. An `S` indicates that a test was skipped because it is not 254applicable to your platform or is particularly expensive. 255 256**Note:** There should be _no_ failing tests when you build an unmodified 257source tree from a [release](https://github.com/libgit2/libgit2/releases), 258or from the [main branch](https://github.com/libgit2/libgit2/tree/main). 259Please contact us or [open an issue](https://github.com/libgit2/libgit2/issues) 260if you see test failures. 261 262Installation 263------------ 264 265To install the library you can specify the install prefix by setting: 266 267 $ cmake .. -DCMAKE_INSTALL_PREFIX=/install/prefix 268 $ cmake --build . --target install 269 270Advanced Usage 271-------------- 272 273For more advanced use or questions about CMake please read <https://cmake.org/Wiki/CMake_FAQ>. 274 275The following CMake variables are declared: 276 277- `CMAKE_INSTALL_BINDIR`: Where to install binaries to. 278- `CMAKE_INSTALL_LIBDIR`: Where to install libraries to. 279- `CMAKE_INSTALL_INCLUDEDIR`: Where to install headers to. 280- `BUILD_SHARED_LIBS`: Build libgit2 as a Shared Library (defaults to ON) 281- `BUILD_CLAR`: Build [Clar](https://github.com/vmg/clar)-based test suite (defaults to ON) 282- `THREADSAFE`: Build libgit2 with threading support (defaults to ON) 283 284To list all build options and their current value, you can do the 285following: 286 287 # Create and set up a build directory 288 $ mkdir build 289 $ cmake .. 290 # List all build options and their values 291 $ cmake -L 292 293Compiler and linker options 294--------------------------- 295 296CMake lets you specify a few variables to control the behavior of the 297compiler and linker. These flags are rarely used but can be useful for 29864-bit to 32-bit cross-compilation. 299 300- `CMAKE_C_FLAGS`: Set your own compiler flags 301- `CMAKE_FIND_ROOT_PATH`: Override the search path for libraries 302- `ZLIB_LIBRARY`, `OPENSSL_SSL_LIBRARY` AND `OPENSSL_CRYPTO_LIBRARY`: 303Tell CMake where to find those specific libraries 304 305MacOS X 306------- 307 308If you want to build a universal binary for Mac OS X, CMake sets it 309all up for you if you use `-DCMAKE_OSX_ARCHITECTURES="i386;x86_64"` 310when configuring. 311 312Android 313------- 314 315Extract toolchain from NDK using, `make-standalone-toolchain.sh` script. 316Optionally, crosscompile and install OpenSSL inside of it. Then create CMake 317toolchain file that configures paths to your crosscompiler (substitute `{PATH}` 318with full path to the toolchain): 319 320 SET(CMAKE_SYSTEM_NAME Linux) 321 SET(CMAKE_SYSTEM_VERSION Android) 322 323 SET(CMAKE_C_COMPILER {PATH}/bin/arm-linux-androideabi-gcc) 324 SET(CMAKE_CXX_COMPILER {PATH}/bin/arm-linux-androideabi-g++) 325 SET(CMAKE_FIND_ROOT_PATH {PATH}/sysroot/) 326 327 SET(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER) 328 SET(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY) 329 SET(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY) 330 331Add `-DCMAKE_TOOLCHAIN_FILE={pathToToolchainFile}` to cmake command 332when configuring. 333 334MinGW 335----- 336 337If you want to build the library in MinGW environment with SSH support enabled, 338you may need to pass `-DCMAKE_LIBRARY_PATH="${MINGW_PREFIX}/${MINGW_CHOST}/lib/"` flag 339to CMake when configuring. This is because CMake cannot find the Win32 libraries in 340MinGW folders by default and you might see an error message stating that CMake 341could not resolve `ws2_32` library during configuration. 342 343Another option would be to install `msys2-w32api-runtime` package before configuring. 344This package installs the Win32 libraries into `/usr/lib` folder which is by default 345recognized as the library path by CMake. Please note though that this package is meant 346for MSYS subsystem which is different from MinGW. 347 348Language Bindings 349================================== 350 351Here are the bindings to libgit2 that are currently available: 352 353* C++ 354 * libqgit2, Qt bindings <https://projects.kde.org/projects/playground/libs/libqgit2/repository/> 355* Chicken Scheme 356 * chicken-git <https://wiki.call-cc.org/egg/git> 357* D 358 * dlibgit <https://github.com/s-ludwig/dlibgit> 359* Delphi 360 * GitForDelphi <https://github.com/libgit2/GitForDelphi> 361 * libgit2-delphi <https://github.com/todaysoftware/libgit2-delphi> 362* Erlang 363 * Geef <https://github.com/carlosmn/geef> 364* Go 365 * git2go <https://github.com/libgit2/git2go> 366* GObject 367 * libgit2-glib <https://wiki.gnome.org/Projects/Libgit2-glib> 368* Guile 369 * Guile-Git <https://gitlab.com/guile-git/guile-git> 370* Haskell 371 * hgit2 <https://github.com/jwiegley/gitlib> 372* Java 373 * Jagged <https://github.com/ethomson/jagged> 374 * Git24j <https://github.com/git24j/git24j> 375* Javascript / WebAssembly ( browser and nodejs ) 376 * WASM-git <https://github.com/petersalomonsen/wasm-git> 377* Julia 378 * LibGit2.jl <https://github.com/JuliaLang/julia/tree/master/stdlib/LibGit2> 379* Lua 380 * luagit2 <https://github.com/libgit2/luagit2> 381* .NET 382 * libgit2sharp <https://github.com/libgit2/libgit2sharp> 383* Node.js 384 * nodegit <https://github.com/nodegit/nodegit> 385* Objective-C 386 * objective-git <https://github.com/libgit2/objective-git> 387* OCaml 388 * ocaml-libgit2 <https://github.com/fxfactorial/ocaml-libgit2> 389* Parrot Virtual Machine 390 * parrot-libgit2 <https://github.com/letolabs/parrot-libgit2> 391* Perl 392 * Git-Raw <https://github.com/jacquesg/p5-Git-Raw> 393* PHP 394 * php-git <https://github.com/libgit2/php-git> 395* PowerShell 396 * PSGit <https://github.com/PoshCode/PSGit> 397* Python 398 * pygit2 <https://github.com/libgit2/pygit2> 399* R 400 * gert <https://docs.ropensci.org/gert> 401 * git2r <https://github.com/ropensci/git2r> 402* Ruby 403 * Rugged <https://github.com/libgit2/rugged> 404* Rust 405 * git2-rs <https://github.com/rust-lang/git2-rs> 406* Swift 407 * SwiftGit2 <https://github.com/SwiftGit2/SwiftGit2> 408* Vala 409 * libgit2.vapi <https://github.com/apmasell/vapis/blob/master/libgit2.vapi> 410 411If you start another language binding to libgit2, please let us know so 412we can add it to the list. 413 414How Can I Contribute? 415================================== 416 417We welcome new contributors! We have a number of issues marked as 418["up for grabs"](https://github.com/libgit2/libgit2/issues?q=is%3Aissue+is%3Aopen+label%3A%22up+for+grabs%22) 419and 420["easy fix"](https://github.com/libgit2/libgit2/issues?utf8=✓&q=is%3Aissue+is%3Aopen+label%3A%22easy+fix%22) 421that are good places to jump in and get started. There's much more detailed 422information in our list of [outstanding projects](docs/projects.md). 423 424Please be sure to check the [contribution guidelines](docs/contributing.md) to 425understand our workflow, and the libgit2 [coding conventions](docs/conventions.md). 426 427License 428================================== 429 430`libgit2` is under GPL2 **with linking exception**. This means you can link to 431and use the library from any program, proprietary or open source; paid or 432gratis. However, if you modify libgit2 itself, you must distribute the 433source to your modified version of libgit2. 434 435See the [COPYING file](COPYING) for the full license text. 436