README.md

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