]>
Commit | Line | Data |
---|---|---|
4b7483a2 | 1 | libgit2 - the Git linkable library |
20b5d300 | 2 | ================================== |
4b7483a2 | 3 | |
c5c8ece1 | 4 | [![Travis Build Status](https://secure.travis-ci.org/libgit2/libgit2.svg?branch=master)](http://travis-ci.org/libgit2/libgit2) |
7cfbf3b7 | 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) |
4caf0df0 | 6 | [![Coverity Scan Build Status](https://scan.coverity.com/projects/639/badge.svg)](https://scan.coverity.com/projects/639) |
37029314 | 7 | |
486bc366 RB |
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. | |
4b7483a2 | 11 | |
dcfdb977 BS |
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). | |
b760fbf5 | 17 | |
2976dcf8 ET |
18 | Getting Help |
19 | ============ | |
3e3d332b | 20 | |
2976dcf8 ET |
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. | |
4b7483a2 SC |
42 | |
43 | What It Can Do | |
20b5d300 | 44 | ============== |
4b7483a2 | 45 | |
486bc366 RB |
46 | `libgit2` is already very usable and is being used in production for many |
47 | applications including the GitHub.com site, in Plastic SCM and also powering | |
48 | Microsoft's Visual Studio tools for Git. The library provides: | |
c5b97d5a | 49 | |
b760fbf5 | 50 | * SHA conversions, formatting and shortening |
5689a8d5 | 51 | * abstracted ODB backend system |
7548b8af | 52 | * commit, tag, tree and blob parsing, editing, and write-back |
4b7483a2 | 53 | * tree traversal |
b760fbf5 VM |
54 | * revision walking |
55 | * index file (staging area) manipulation | |
b760fbf5 | 56 | * reference management (including packed references) |
7548b8af VM |
57 | * config file management |
58 | * high level repository management | |
59 | * thread safety and reentrancy | |
60 | * descriptive and detailed error messages | |
61 | * ...and more (over 175 different API calls) | |
b760fbf5 | 62 | |
2baee9f8 CMN |
63 | Optional dependencies |
64 | ===================== | |
65 | ||
66 | While the library provides git functionality without the need for | |
67 | dependencies, it can make use of a few libraries to add to it: | |
68 | ||
69 | - pthreads (non-Windows) to enable threadsafe access as well as multi-threaded pack generation | |
70 | - OpenSSL (non-Windows) to talk over HTTPS and provide the SHA-1 functions | |
2c22193b | 71 | - LibSSH2 to enable the SSH transport |
2baee9f8 CMN |
72 | - iconv (OSX) to handle the HFS+ path encoding peculiarities |
73 | ||
ed09e044 CMN |
74 | Initialization |
75 | =============== | |
76 | ||
77 | The library needs to keep track of some global state. Call | |
78 | ||
79 | git_libgit2_init(); | |
80 | ||
81 | before calling any other libgit2 functions. You can call this function many times. A matching number of calls to | |
82 | ||
83 | git_libgit2_shutdown(); | |
84 | ||
ecf1c3c3 ET |
85 | will free the resources. Note that if you have worker threads, you should |
86 | call `git_libgit2_shutdown` *after* those threads have exited. If you | |
87 | require assistance coordinating this, simply have the worker threads call | |
88 | `git_libgit2_init` at startup and `git_libgit2_shutdown` at shutdown. | |
ed09e044 | 89 | |
15bea02c CMN |
90 | Threading |
91 | ========= | |
92 | ||
93 | See [THREADING](THREADING.md) for information | |
94 | ||
1f8cb02f CMN |
95 | Conventions |
96 | =========== | |
97 | ||
98 | See [CONVENTIONS](CONVENTIONS.md) for an overview of the external | |
99 | and internal API/coding conventions we use. | |
100 | ||
7548b8af VM |
101 | Building libgit2 - Using CMake |
102 | ============================== | |
ec821ca6 | 103 | |
20b5d300 | 104 | `libgit2` builds cleanly on most platforms without any external dependencies. |
a07d8994 | 105 | Under Unix-like systems, like Linux, \*BSD and Mac OS X, libgit2 expects `pthreads` to be available; |
bbcc7ffc VM |
106 | they should be installed by default on all systems. Under Windows, libgit2 uses the native Windows API |
107 | for threading. | |
108 | ||
1181ca0c | 109 | The `libgit2` library is built using [CMake](<https://cmake.org/>) (version 2.8 or newer) on all platforms. |
4b7483a2 | 110 | |
e0d9e12e | 111 | On most systems you can build the library using the following commands |
4b7483a2 | 112 | |
e0d9e12e VM |
113 | $ mkdir build && cd build |
114 | $ cmake .. | |
115 | $ cmake --build . | |
c5b97d5a | 116 | |
e0d9e12e VM |
117 | Alternatively you can point the CMake GUI tool to the CMakeLists.txt file and generate platform specific build project or IDE workspace. |
118 | ||
119 | To install the library you can specify the install prefix by setting: | |
4b7483a2 | 120 | |
e0d9e12e VM |
121 | $ cmake .. -DCMAKE_INSTALL_PREFIX=/install/prefix |
122 | $ cmake --build . --target install | |
4b7483a2 | 123 | |
1181ca0c | 124 | For more advanced use or questions about CMake please read <https://cmake.org/Wiki/CMake_FAQ>. |
c5b97d5a | 125 | |
7548b8af VM |
126 | The following CMake variables are declared: |
127 | ||
9795a40f | 128 | - `BIN_INSTALL_DIR`: Where to install binaries to. |
77ace82d | 129 | - `LIB_INSTALL_DIR`: Where to install libraries to. |
9795a40f | 130 | - `INCLUDE_INSTALL_DIR`: Where to install headers to. |
f0890fcc | 131 | - `BUILD_SHARED_LIBS`: Build libgit2 as a Shared Library (defaults to ON) |
221ee54b | 132 | - `BUILD_CLAR`: Build [Clar](https://github.com/vmg/clar)-based test suite (defaults to ON) |
79b0ae4e | 133 | - `THREADSAFE`: Build libgit2 with threading support (defaults to ON) |
66bf4dbc CMN |
134 | - `STDCALL`: Build libgit2 as `stdcall`. Turn off for `cdecl` (Windows; defaults to ON) |
135 | ||
136 | Compiler and linker options | |
137 | --------------------------- | |
138 | ||
139 | CMake lets you specify a few variables to control the behavior of the | |
140 | compiler and linker. These flags are rarely used but can be useful for | |
141 | 64-bit to 32-bit cross-compilation. | |
142 | ||
143 | - `CMAKE_C_FLAGS`: Set your own compiler flags | |
144 | - `CMAKE_FIND_ROOT_PATH`: Override the search path for libraries | |
145 | - `ZLIB_LIBRARY`, `OPENSSL_SSL_LIBRARY` AND `OPENSSL_CRYPTO_LIBRARY`: | |
146 | Tell CMake where to find those specific libraries | |
147 | ||
148 | MacOS X | |
149 | ------- | |
150 | ||
151 | If you want to build a universal binary for Mac OS X, CMake sets it | |
152 | all up for you if you use `-DCMAKE_OSX_ARCHITECTURES="i386;x86_64"` | |
153 | when configuring. | |
154 | ||
155 | Windows | |
156 | ------- | |
157 | ||
158 | You need to run the CMake commands from the Visual Studio command | |
159 | prompt, not the regular or Windows SDK one. Select the right generator | |
160 | for your version with the `-G "Visual Studio X" option. | |
161 | ||
1181ca0c | 162 | See [the website](http://libgit2.github.com/docs/guides/build-and-link/) |
66bf4dbc | 163 | for more detailed instructions. |
c5b97d5a | 164 | |
01cd5ae3 KA |
165 | Android |
166 | ------- | |
167 | ||
168 | Extract toolchain from NDK using, `make-standalone-toolchain.sh` script. | |
63d1fad4 NK |
169 | Optionally, crosscompile and install OpenSSL inside of it. Then create CMake |
170 | toolchain file that configures paths to your crosscompiler (substitute `{PATH}` | |
01cd5ae3 KA |
171 | with full path to the toolchain): |
172 | ||
173 | SET(CMAKE_SYSTEM_NAME Linux) | |
174 | SET(CMAKE_SYSTEM_VERSION Android) | |
775d831b | 175 | |
01cd5ae3 KA |
176 | SET(CMAKE_C_COMPILER {PATH}/bin/arm-linux-androideabi-gcc) |
177 | SET(CMAKE_CXX_COMPILER {PATH}/bin/arm-linux-androideabi-g++) | |
178 | SET(CMAKE_FIND_ROOT_PATH {PATH}/sysroot/) | |
775d831b | 179 | |
01cd5ae3 KA |
180 | SET(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER) |
181 | SET(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY) | |
182 | SET(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY) | |
183 | ||
57aa839c | 184 | Add `-DCMAKE_TOOLCHAIN_FILE={pathToToolchainFile}` to cmake command |
01cd5ae3 KA |
185 | when configuring. |
186 | ||
e0d9e12e VM |
187 | Language Bindings |
188 | ================================== | |
4b7483a2 | 189 | |
e0d9e12e | 190 | Here are the bindings to libgit2 that are currently available: |
4b7483a2 | 191 | |
b8d08292 AL |
192 | * C++ |
193 | * libqgit2, Qt bindings <https://projects.kde.org/projects/playground/libs/libqgit2/> | |
0e8144fe EH |
194 | * Chicken Scheme |
195 | * chicken-git <https://wiki.call-cc.org/egg/git> | |
26127ea7 | 196 | * D |
e702dc2e | 197 | * dlibgit <https://github.com/s-ludwig/dlibgit> |
b8d08292 AL |
198 | * Delphi |
199 | * GitForDelphi <https://github.com/libgit2/GitForDelphi> | |
200 | * Erlang | |
a402179a | 201 | * Geef <https://github.com/carlosmn/geef> |
b8d08292 | 202 | * Go |
f2cda906 | 203 | * git2go <https://github.com/libgit2/git2go> |
b8d08292 | 204 | * GObject |
1ce509fe | 205 | * libgit2-glib <https://wiki.gnome.org/Projects/Libgit2-glib> |
b8d08292 | 206 | * Haskell |
1181ca0c | 207 | * hgit2 <https://github.com/jwiegley/gitlib> |
4ef9a508 ET |
208 | * Java |
209 | * Jagged <https://github.com/ethomson/jagged> | |
d747ec18 | 210 | * Julia |
211 | * LibGit2.jl <https://github.com/jakebolewski/LibGit2.jl> | |
b8d08292 AL |
212 | * Lua |
213 | * luagit2 <https://github.com/libgit2/luagit2> | |
214 | * .NET | |
b8d08292 AL |
215 | * libgit2sharp <https://github.com/libgit2/libgit2sharp> |
216 | * Node.js | |
1181ca0c | 217 | * nodegit <https://github.com/nodegit/nodegit> |
b8d08292 AL |
218 | * Objective-C |
219 | * objective-git <https://github.com/libgit2/objective-git> | |
220 | * OCaml | |
69560cc0 | 221 | * ocaml-libgit2 <https://github.com/fxfactorial/ocaml-libgit2> |
b8d08292 AL |
222 | * Parrot Virtual Machine |
223 | * parrot-libgit2 <https://github.com/letolabs/parrot-libgit2> | |
224 | * Perl | |
2ef20da0 | 225 | * Git-Raw <https://github.com/jacquesg/p5-Git-Raw> |
b8d08292 AL |
226 | * PHP |
227 | * php-git <https://github.com/libgit2/php-git> | |
4ef9a508 | 228 | * PowerShell |
738ca6ee | 229 | * PSGit <https://github.com/PoshCode/PSGit> |
b8d08292 AL |
230 | * Python |
231 | * pygit2 <https://github.com/libgit2/pygit2> | |
562516ec SW |
232 | * R |
233 | * git2r <https://github.com/ropensci/git2r> | |
b8d08292 AL |
234 | * Ruby |
235 | * Rugged <https://github.com/libgit2/rugged> | |
b4913705 AC |
236 | * Rust |
237 | * git2-rs <https://github.com/alexcrichton/git2-rs> | |
35425b51 BG |
238 | * Swift |
239 | * Gift <https://github.com/modocache/Gift> | |
b8d08292 AL |
240 | * Vala |
241 | * libgit2.vapi <https://github.com/apmasell/vapis/blob/master/libgit2.vapi> | |
4b7483a2 SC |
242 | |
243 | If you start another language binding to libgit2, please let us know so | |
244 | we can add it to the list. | |
245 | ||
b8d08292 | 246 | How Can I Contribute? |
c5b97d5a SC |
247 | ================================== |
248 | ||
0820d0c8 ET |
249 | We welcome new contributors! We have a number of issues marked as |
250 | ["up for grabs"](https://github.com/libgit2/libgit2/issues?q=is%3Aissue+is%3Aopen+label%3A%22up+for+grabs%22) | |
251 | and | |
252 | ["easy fix"](https://github.com/libgit2/libgit2/issues?utf8=✓&q=is%3Aissue+is%3Aopen+label%3A%22easy+fix%22) | |
253 | that are good places to jump in and get started. There's much more detailed | |
254 | information in our list of [outstanding projects](PROJECTS.md). | |
255 | ||
256 | Please be sure to check the [contribution guidelines](CONTRIBUTING.md) to | |
257 | understand our workflow, and the libgit2 [coding conventions](CONVENTIONS.md). | |
c5b97d5a | 258 | |
932d1baf | 259 | License |
4b7483a2 | 260 | ================================== |
486bc366 | 261 | |
18925129 | 262 | `libgit2` is under GPL2 **with linking exception**. This means you can link to |
486bc366 | 263 | and use the library from any program, proprietary or open source; paid or |
69d11971 ET |
264 | gratis. However, if you modify libgit2 itself, you must distribute the |
265 | source to your modified version of libgit2. | |
4b7483a2 | 266 | |
486bc366 | 267 | See the [COPYING file](COPYING) for the full license text. |