| 1 |
libgit2 - the Git linkable library |
| 2 |
================================== |
| 3 |
|
| 4 |
[](http://travis-ci.org/libgit2/libgit2) |
| 5 |
[](https://ci.appveyor.com/project/libgit2/libgit2/branch/master) |
| 6 |
[](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 [[email protected]](mailto:[email protected]). |
| 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. |