|
| 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 [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_clar |
| 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_clar -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_clar -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_CLAR`: 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. |
0 commit comments