README.md

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