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.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) | 8| **v1.0 branch** CI builds | [![Azure Pipelines Build Status](https://dev.azure.com/libgit2/libgit2/_apis/build/status/libgit2?branchName=maint/v1.0)](https://dev.azure.com/libgit2/libgit2/_build/latest?definitionId=7&branchName=maint/v1.0) | 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://webchat.freenode.net/#libgit2) on Freenode 108- via Slack: visit [slack.libgit2.org](http://slack.libgit2.org/) to sign up, 109 then join us in `#libgit2` 110 111**Getting Help** 112 113If you have questions about the library, please be sure to check out the 114[API documentation](http://libgit2.github.com/libgit2/). If you still have 115questions, reach out to us on Slack or post a question on 116[StackOverflow](http://stackoverflow.com/questions/tagged/libgit2) (with the `libgit2` tag). 117 118**Reporting Bugs** 119 120Please open a [GitHub Issue](https://github.com/libgit2/libgit2/issues) and 121include as much information as possible. If possible, provide sample code 122that illustrates the problem you're seeing. If you're seeing a bug only 123on a specific repository, please provide a link to it if possible. 124 125We ask that you not open a GitHub Issue for help, only for bug reports. 126 127**Reporting Security Issues** 128 129Please have a look at SECURITY.md. 130 131What It Can Do 132============== 133 134libgit2 provides you with the ability to manage Git repositories in the 135programming language of your choice. It's used in production to power many 136applications including GitHub.com, Plastic SCM and Azure DevOps. 137 138It does not aim to replace the git tool or its user-facing commands. Some APIs 139resemble the plumbing commands as those align closely with the concepts of the 140Git system, but most commands a user would type are out of scope for this 141library to implement directly. 142 143The library provides: 144 145* SHA conversions, formatting and shortening 146* abstracted ODB backend system 147* commit, tag, tree and blob parsing, editing, and write-back 148* tree traversal 149* revision walking 150* index file (staging area) manipulation 151* reference management (including packed references) 152* config file management 153* high level repository management 154* thread safety and reentrancy 155* descriptive and detailed error messages 156* ...and more (over 175 different API calls) 157 158As libgit2 is purely a consumer of the Git system, we have to 159adjust to changes made upstream. This has two major consequences: 160 161* Some changes may require us to change provided interfaces. While we try to 162 implement functions in a generic way so that no future changes are required, 163 we cannot promise a completely stable API. 164* As we have to keep up with changes in behavior made upstream, we may lag 165 behind in some areas. We usually to document these incompatibilities in our 166 issue tracker with the label "git change". 167 168Optional dependencies 169===================== 170 171While the library provides git functionality without the need for 172dependencies, it can make use of a few libraries to add to it: 173 174- pthreads (non-Windows) to enable threadsafe access as well as multi-threaded pack generation 175- OpenSSL (non-Windows) to talk over HTTPS and provide the SHA-1 functions 176- LibSSH2 to enable the SSH transport 177- iconv (OSX) to handle the HFS+ path encoding peculiarities 178 179Initialization 180=============== 181 182The library needs to keep track of some global state. Call 183 184 git_libgit2_init(); 185 186before calling any other libgit2 functions. You can call this function many times. A matching number of calls to 187 188 git_libgit2_shutdown(); 189 190will free the resources. Note that if you have worker threads, you should 191call `git_libgit2_shutdown` *after* those threads have exited. If you 192require assistance coordinating this, simply have the worker threads call 193`git_libgit2_init` at startup and `git_libgit2_shutdown` at shutdown. 194 195Threading 196========= 197 198See [threading](docs/threading.md) for information 199 200Conventions 201=========== 202 203See [conventions](docs/conventions.md) for an overview of the external 204and internal API/coding conventions we use. 205 206Building libgit2 - Using CMake 207============================== 208 209Building 210-------- 211 212`libgit2` builds cleanly on most platforms without any external dependencies. 213Under Unix-like systems, like Linux, \*BSD and Mac OS X, libgit2 expects `pthreads` to be available; 214they should be installed by default on all systems. Under Windows, libgit2 uses the native Windows API 215for threading. 216 217The `libgit2` library is built using [CMake](<https://cmake.org/>) (version 2.8 or newer) on all platforms. 218 219On most systems you can build the library using the following commands 220 221 $ mkdir build && cd build 222 $ cmake .. 223 $ cmake --build . 224 225Alternatively you can point the CMake GUI tool to the CMakeLists.txt file and generate platform specific build project or IDE workspace. 226 227Running Tests 228------------- 229 230Once built, you can run the tests from the `build` directory with the command 231 232 $ ctest -V 233 234Alternatively you can run the test suite directly using, 235 236 $ ./libgit2_clar 237 238Invoking the test suite directly is useful because it allows you to execute 239individual tests, or groups of tests using the `-s` flag. For example, to 240run the index tests: 241 242 $ ./libgit2_clar -sindex 243 244To run a single test named `index::racy::diff`, which corresponds to the test 245function [`test_index_racy__diff`](https://github.com/libgit2/libgit2/blob/main/tests/index/racy.c#L23): 246 247 $ ./libgit2_clar -sindex::racy::diff 248 249The test suite will print a `.` for every passing test, and an `F` for any 250failing test. An `S` indicates that a test was skipped because it is not 251applicable to your platform or is particularly expensive. 252 253**Note:** There should be _no_ failing tests when you build an unmodified 254source tree from a [release](https://github.com/libgit2/libgit2/releases), 255or from the [main branch](https://github.com/libgit2/libgit2/tree/main). 256Please contact us or [open an issue](https://github.com/libgit2/libgit2/issues) 257if you see test failures. 258 259Installation 260------------ 261 262To install the library you can specify the install prefix by setting: 263 264 $ cmake .. -DCMAKE_INSTALL_PREFIX=/install/prefix 265 $ cmake --build . --target install 266 267Advanced Usage 268-------------- 269 270For more advanced use or questions about CMake please read <https://cmake.org/Wiki/CMake_FAQ>. 271 272The following CMake variables are declared: 273 274- `CMAKE_INSTALL_BINDIR`: Where to install binaries to. 275- `CMAKE_INSTALL_LIBDIR`: Where to install libraries to. 276- `CMAKE_INSTALL_INCLUDEDIR`: Where to install headers to. 277- `BUILD_SHARED_LIBS`: Build libgit2 as a Shared Library (defaults to ON) 278- `BUILD_CLAR`: Build [Clar](https://github.com/vmg/clar)-based test suite (defaults to ON) 279- `THREADSAFE`: Build libgit2 with threading support (defaults to ON) 280 281To list all build options and their current value, you can do the 282following: 283 284 # Create and set up a build directory 285 $ mkdir build 286 $ cmake .. 287 # List all build options and their values 288 $ cmake -L 289 290Compiler and linker options 291--------------------------- 292 293CMake lets you specify a few variables to control the behavior of the 294compiler and linker. These flags are rarely used but can be useful for 29564-bit to 32-bit cross-compilation. 296 297- `CMAKE_C_FLAGS`: Set your own compiler flags 298- `CMAKE_FIND_ROOT_PATH`: Override the search path for libraries 299- `ZLIB_LIBRARY`, `OPENSSL_SSL_LIBRARY` AND `OPENSSL_CRYPTO_LIBRARY`: 300Tell CMake where to find those specific libraries 301 302MacOS X 303------- 304 305If you want to build a universal binary for Mac OS X, CMake sets it 306all up for you if you use `-DCMAKE_OSX_ARCHITECTURES="i386;x86_64"` 307when configuring. 308 309Android 310------- 311 312Extract toolchain from NDK using, `make-standalone-toolchain.sh` script. 313Optionally, crosscompile and install OpenSSL inside of it. Then create CMake 314toolchain file that configures paths to your crosscompiler (substitute `{PATH}` 315with full path to the toolchain): 316 317 SET(CMAKE_SYSTEM_NAME Linux) 318 SET(CMAKE_SYSTEM_VERSION Android) 319 320 SET(CMAKE_C_COMPILER {PATH}/bin/arm-linux-androideabi-gcc) 321 SET(CMAKE_CXX_COMPILER {PATH}/bin/arm-linux-androideabi-g++) 322 SET(CMAKE_FIND_ROOT_PATH {PATH}/sysroot/) 323 324 SET(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER) 325 SET(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY) 326 SET(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY) 327 328Add `-DCMAKE_TOOLCHAIN_FILE={pathToToolchainFile}` to cmake command 329when configuring. 330 331MinGW 332----- 333 334If you want to build the library in MinGW environment with SSH support enabled, 335you may need to pass `-DCMAKE_LIBRARY_PATH="${MINGW_PREFIX}/${MINGW_CHOST}/lib/"` flag 336to CMake when configuring. This is because CMake cannot find the Win32 libraries in 337MinGW folders by default and you might see an error message stating that CMake 338could not resolve `ws2_32` library during configuration. 339 340Another option would be to install `msys2-w32api-runtime` package before configuring. 341This package installs the Win32 libraries into `/usr/lib` folder which is by default 342recognized as the library path by CMake. Please note though that this package is meant 343for MSYS subsystem which is different from MinGW. 344 345Language Bindings 346================================== 347 348Here are the bindings to libgit2 that are currently available: 349 350* C++ 351 * libqgit2, Qt bindings <https://projects.kde.org/projects/playground/libs/libqgit2/repository/> 352* Chicken Scheme 353 * chicken-git <https://wiki.call-cc.org/egg/git> 354* D 355 * dlibgit <https://github.com/s-ludwig/dlibgit> 356* Delphi 357 * GitForDelphi <https://github.com/libgit2/GitForDelphi> 358* Erlang 359 * Geef <https://github.com/carlosmn/geef> 360* Go 361 * git2go <https://github.com/libgit2/git2go> 362* GObject 363 * libgit2-glib <https://wiki.gnome.org/Projects/Libgit2-glib> 364* Guile 365 * Guile-Git <https://gitlab.com/guile-git/guile-git> 366* Haskell 367 * hgit2 <https://github.com/jwiegley/gitlib> 368* Java 369 * Jagged <https://github.com/ethomson/jagged> 370* Javascript / WebAssembly ( browser and nodejs ) 371 * WASM-git <https://github.com/petersalomonsen/wasm-git> 372* Julia 373 * LibGit2.jl <https://github.com/JuliaLang/julia/tree/master/stdlib/LibGit2> 374* Lua 375 * luagit2 <https://github.com/libgit2/luagit2> 376* .NET 377 * libgit2sharp <https://github.com/libgit2/libgit2sharp> 378* Node.js 379 * nodegit <https://github.com/nodegit/nodegit> 380* Objective-C 381 * objective-git <https://github.com/libgit2/objective-git> 382* OCaml 383 * ocaml-libgit2 <https://github.com/fxfactorial/ocaml-libgit2> 384* Parrot Virtual Machine 385 * parrot-libgit2 <https://github.com/letolabs/parrot-libgit2> 386* Perl 387 * Git-Raw <https://github.com/jacquesg/p5-Git-Raw> 388* PHP 389 * php-git <https://github.com/libgit2/php-git> 390* PowerShell 391 * PSGit <https://github.com/PoshCode/PSGit> 392* Python 393 * pygit2 <https://github.com/libgit2/pygit2> 394* R 395 * gert <https://docs.ropensci.org/gert> 396 * git2r <https://github.com/ropensci/git2r> 397* Ruby 398 * Rugged <https://github.com/libgit2/rugged> 399* Rust 400 * git2-rs <https://github.com/rust-lang/git2-rs> 401* Swift 402 * SwiftGit2 <https://github.com/SwiftGit2/SwiftGit2> 403* Vala 404 * libgit2.vapi <https://github.com/apmasell/vapis/blob/master/libgit2.vapi> 405 406If you start another language binding to libgit2, please let us know so 407we can add it to the list. 408 409How Can I Contribute? 410================================== 411 412We welcome new contributors! We have a number of issues marked as 413["up for grabs"](https://github.com/libgit2/libgit2/issues?q=is%3Aissue+is%3Aopen+label%3A%22up+for+grabs%22) 414and 415["easy fix"](https://github.com/libgit2/libgit2/issues?utf8=✓&q=is%3Aissue+is%3Aopen+label%3A%22easy+fix%22) 416that are good places to jump in and get started. There's much more detailed 417information in our list of [outstanding projects](docs/projects.md). 418 419Please be sure to check the [contribution guidelines](docs/contributing.md) to 420understand our workflow, and the libgit2 [coding conventions](docs/conventions.md). 421 422License 423================================== 424 425`libgit2` is under GPL2 **with linking exception**. This means you can link to 426and use the library from any program, proprietary or open source; paid or 427gratis. However, if you modify libgit2 itself, you must distribute the 428source to your modified version of libgit2. 429 430See the [COPYING file](COPYING) for the full license text. 431