fuzzers/corpora/objects/blob

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