]>
Commit | Line | Data |
---|---|---|
4b7483a2 | 1 | libgit2 - the Git linkable library |
20b5d300 | 2 | ================================== |
4b7483a2 | 3 | |
37029314 | 4 | [![Build Status](https://secure.travis-ci.org/libgit2/libgit2.png?branch=development)](http://travis-ci.org/libgit2/libgit2) |
4caf0df0 | 5 | [![Coverity Scan Build Status](https://scan.coverity.com/projects/639/badge.svg)](https://scan.coverity.com/projects/639) |
37029314 | 6 | |
486bc366 RB |
7 | `libgit2` is a portable, pure C implementation of the Git core methods |
8 | provided as a re-entrant linkable library with a solid API, allowing you to | |
9 | write native speed custom Git applications in any language with bindings. | |
4b7483a2 | 10 | |
dcfdb977 BS |
11 | `libgit2` is licensed under a **very permissive license** (GPLv2 with a special |
12 | Linking Exception). This basically means that you can link it (unmodified) | |
13 | with any kind of software without having to release its source code. | |
14 | Additionally, the example code has been released to the public domain (see the | |
15 | [separate license](examples/COPYING) for more information). | |
b760fbf5 | 16 | |
20b5d300 | 17 | * Website: [libgit2.github.com](http://libgit2.github.com) |
3e3d332b | 18 | * StackOverflow Tag: [libgit2](http://stackoverflow.com/questions/tagged/libgit2) |
20b5d300 | 19 | * Issues: [GitHub Issues](https://github.com/libgit2/libgit2/issues) (Right here!) |
e49020e0 | 20 | * API documentation: <http://libgit2.github.com/libgit2> |
20b5d300 | 21 | * IRC: [#libgit2](irc://irc.freenode.net/libgit2) on irc.freenode.net. |
3e3d332b | 22 | * Mailing list: The libgit2 mailing list was |
68a19ca9 | 23 | traditionally hosted in Librelist but has been deprecated. We encourage you to |
41a93cc6 | 24 | [use StackOverflow](http://stackoverflow.com/questions/tagged/libgit2) instead for any questions regarding |
68a19ca9 RB |
25 | the library, or [open an issue](https://github.com/libgit2/libgit2/issues) |
26 | on GitHub for bug reports. The mailing list archives are still available at | |
3e3d332b MW |
27 | <http://librelist.com/browser/libgit2/>. |
28 | ||
4b7483a2 SC |
29 | |
30 | What It Can Do | |
20b5d300 | 31 | ============== |
4b7483a2 | 32 | |
486bc366 RB |
33 | `libgit2` is already very usable and is being used in production for many |
34 | applications including the GitHub.com site, in Plastic SCM and also powering | |
35 | Microsoft's Visual Studio tools for Git. The library provides: | |
c5b97d5a | 36 | |
b760fbf5 | 37 | * SHA conversions, formatting and shortening |
5689a8d5 | 38 | * abstracted ODB backend system |
7548b8af | 39 | * commit, tag, tree and blob parsing, editing, and write-back |
4b7483a2 | 40 | * tree traversal |
b760fbf5 VM |
41 | * revision walking |
42 | * index file (staging area) manipulation | |
b760fbf5 | 43 | * reference management (including packed references) |
7548b8af VM |
44 | * config file management |
45 | * high level repository management | |
46 | * thread safety and reentrancy | |
47 | * descriptive and detailed error messages | |
48 | * ...and more (over 175 different API calls) | |
b760fbf5 | 49 | |
2baee9f8 CMN |
50 | Optional dependencies |
51 | ===================== | |
52 | ||
53 | While the library provides git functionality without the need for | |
54 | dependencies, it can make use of a few libraries to add to it: | |
55 | ||
56 | - pthreads (non-Windows) to enable threadsafe access as well as multi-threaded pack generation | |
57 | - OpenSSL (non-Windows) to talk over HTTPS and provide the SHA-1 functions | |
58 | - LibSSH2 to enable the ssh transport | |
59 | - iconv (OSX) to handle the HFS+ path encoding peculiarities | |
60 | ||
7548b8af VM |
61 | Building libgit2 - Using CMake |
62 | ============================== | |
ec821ca6 | 63 | |
20b5d300 | 64 | `libgit2` builds cleanly on most platforms without any external dependencies. |
a07d8994 | 65 | Under Unix-like systems, like Linux, \*BSD and Mac OS X, libgit2 expects `pthreads` to be available; |
bbcc7ffc VM |
66 | they should be installed by default on all systems. Under Windows, libgit2 uses the native Windows API |
67 | for threading. | |
68 | ||
68a19ca9 | 69 | The `libgit2` library is built using [CMake](<http://www.cmake.org>) (version 2.6 or newer) on all platforms. |
4b7483a2 | 70 | |
e0d9e12e | 71 | On most systems you can build the library using the following commands |
4b7483a2 | 72 | |
e0d9e12e VM |
73 | $ mkdir build && cd build |
74 | $ cmake .. | |
75 | $ cmake --build . | |
c5b97d5a | 76 | |
e0d9e12e VM |
77 | Alternatively you can point the CMake GUI tool to the CMakeLists.txt file and generate platform specific build project or IDE workspace. |
78 | ||
79 | To install the library you can specify the install prefix by setting: | |
4b7483a2 | 80 | |
e0d9e12e VM |
81 | $ cmake .. -DCMAKE_INSTALL_PREFIX=/install/prefix |
82 | $ cmake --build . --target install | |
4b7483a2 | 83 | |
e0d9e12e | 84 | For more advanced use or questions about CMake please read <http://www.cmake.org/Wiki/CMake_FAQ>. |
c5b97d5a | 85 | |
7548b8af VM |
86 | The following CMake variables are declared: |
87 | ||
9795a40f | 88 | - `BIN_INSTALL_DIR`: Where to install binaries to. |
77ace82d | 89 | - `LIB_INSTALL_DIR`: Where to install libraries to. |
9795a40f | 90 | - `INCLUDE_INSTALL_DIR`: Where to install headers to. |
f0890fcc | 91 | - `BUILD_SHARED_LIBS`: Build libgit2 as a Shared Library (defaults to ON) |
221ee54b | 92 | - `BUILD_CLAR`: Build [Clar](https://github.com/vmg/clar)-based test suite (defaults to ON) |
7548b8af | 93 | - `THREADSAFE`: Build libgit2 with threading support (defaults to OFF) |
66bf4dbc CMN |
94 | - `STDCALL`: Build libgit2 as `stdcall`. Turn off for `cdecl` (Windows; defaults to ON) |
95 | ||
96 | Compiler and linker options | |
97 | --------------------------- | |
98 | ||
99 | CMake lets you specify a few variables to control the behavior of the | |
100 | compiler and linker. These flags are rarely used but can be useful for | |
101 | 64-bit to 32-bit cross-compilation. | |
102 | ||
103 | - `CMAKE_C_FLAGS`: Set your own compiler flags | |
104 | - `CMAKE_FIND_ROOT_PATH`: Override the search path for libraries | |
105 | - `ZLIB_LIBRARY`, `OPENSSL_SSL_LIBRARY` AND `OPENSSL_CRYPTO_LIBRARY`: | |
106 | Tell CMake where to find those specific libraries | |
107 | ||
108 | MacOS X | |
109 | ------- | |
110 | ||
111 | If you want to build a universal binary for Mac OS X, CMake sets it | |
112 | all up for you if you use `-DCMAKE_OSX_ARCHITECTURES="i386;x86_64"` | |
113 | when configuring. | |
114 | ||
115 | Windows | |
116 | ------- | |
117 | ||
118 | You need to run the CMake commands from the Visual Studio command | |
119 | prompt, not the regular or Windows SDK one. Select the right generator | |
120 | for your version with the `-G "Visual Studio X" option. | |
121 | ||
122 | See [the wiki] | |
123 | (https://github.com/libgit2/libgit2/wiki/Building-libgit2-on-Windows) | |
124 | for more detailed instructions. | |
c5b97d5a | 125 | |
01cd5ae3 KA |
126 | Android |
127 | ------- | |
128 | ||
129 | Extract toolchain from NDK using, `make-standalone-toolchain.sh` script. | |
63d1fad4 NK |
130 | Optionally, crosscompile and install OpenSSL inside of it. Then create CMake |
131 | toolchain file that configures paths to your crosscompiler (substitute `{PATH}` | |
01cd5ae3 KA |
132 | with full path to the toolchain): |
133 | ||
134 | SET(CMAKE_SYSTEM_NAME Linux) | |
135 | SET(CMAKE_SYSTEM_VERSION Android) | |
136 | ||
137 | SET(CMAKE_C_COMPILER {PATH}/bin/arm-linux-androideabi-gcc) | |
138 | SET(CMAKE_CXX_COMPILER {PATH}/bin/arm-linux-androideabi-g++) | |
139 | SET(CMAKE_FIND_ROOT_PATH {PATH}/sysroot/) | |
140 | ||
141 | SET(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER) | |
142 | SET(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY) | |
143 | SET(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY) | |
144 | ||
145 | Add `-DCMAKE_TOOLCHAIN_FILE={pathToToolchainFile} -DANDROID=1` to cmake command | |
146 | when configuring. | |
147 | ||
e0d9e12e VM |
148 | Language Bindings |
149 | ================================== | |
4b7483a2 | 150 | |
e0d9e12e | 151 | Here are the bindings to libgit2 that are currently available: |
4b7483a2 | 152 | |
b8d08292 AL |
153 | * C++ |
154 | * libqgit2, Qt bindings <https://projects.kde.org/projects/playground/libs/libqgit2/> | |
0e8144fe EH |
155 | * Chicken Scheme |
156 | * chicken-git <https://wiki.call-cc.org/egg/git> | |
26127ea7 AM |
157 | * D |
158 | * dlibgit <https://github.com/AndrejMitrovic/dlibgit> | |
b8d08292 AL |
159 | * Delphi |
160 | * GitForDelphi <https://github.com/libgit2/GitForDelphi> | |
161 | * Erlang | |
a402179a | 162 | * Geef <https://github.com/carlosmn/geef> |
b8d08292 | 163 | * Go |
f2cda906 | 164 | * git2go <https://github.com/libgit2/git2go> |
b8d08292 | 165 | * GObject |
a7a2fccd | 166 | * libgit2-glib <https://live.gnome.org/Libgit2-glib> |
b8d08292 | 167 | * Haskell |
7d5b0f8b | 168 | * hgit2 <https://github.com/fpco/gitlib> |
4ef9a508 ET |
169 | * Java |
170 | * Jagged <https://github.com/ethomson/jagged> | |
b8d08292 AL |
171 | * Lua |
172 | * luagit2 <https://github.com/libgit2/luagit2> | |
173 | * .NET | |
b8d08292 AL |
174 | * libgit2sharp <https://github.com/libgit2/libgit2sharp> |
175 | * Node.js | |
176 | * node-gitteh <https://github.com/libgit2/node-gitteh> | |
177 | * nodegit <https://github.com/tbranyen/nodegit> | |
178 | * Objective-C | |
179 | * objective-git <https://github.com/libgit2/objective-git> | |
180 | * OCaml | |
181 | * libgit2-ocaml <https://github.com/burdges/libgit2-ocaml> | |
182 | * Parrot Virtual Machine | |
183 | * parrot-libgit2 <https://github.com/letolabs/parrot-libgit2> | |
184 | * Perl | |
1cfaaa9e | 185 | * Git-Raw <https://github.com/ghedo/p5-Git-Raw> |
b8d08292 AL |
186 | * PHP |
187 | * php-git <https://github.com/libgit2/php-git> | |
4ef9a508 ET |
188 | * PowerShell |
189 | * GitPowerShell <https://github.com/ethomson/gitpowershell> | |
b8d08292 AL |
190 | * Python |
191 | * pygit2 <https://github.com/libgit2/pygit2> | |
192 | * Ruby | |
193 | * Rugged <https://github.com/libgit2/rugged> | |
194 | * Vala | |
195 | * libgit2.vapi <https://github.com/apmasell/vapis/blob/master/libgit2.vapi> | |
4b7483a2 SC |
196 | |
197 | If you start another language binding to libgit2, please let us know so | |
198 | we can add it to the list. | |
199 | ||
b8d08292 | 200 | How Can I Contribute? |
c5b97d5a SC |
201 | ================================== |
202 | ||
486bc366 RB |
203 | Check the [contribution guidelines](CONTRIBUTING.md) to understand our |
204 | workflow, the libgit2 [coding conventions](CONVENTIONS.md), and out list of | |
205 | [good starting projects](PROJECTS.md). | |
c5b97d5a | 206 | |
932d1baf | 207 | License |
4b7483a2 | 208 | ================================== |
486bc366 RB |
209 | |
210 | `libgit2` is under GPL2 **with linking exemption**. This means you can link to | |
211 | and use the library from any program, proprietary or open source; paid or | |
212 | gratis. However, you cannot modify libgit2 and distribute it without | |
4b7483a2 SC |
213 | supplying the source. |
214 | ||
486bc366 | 215 | See the [COPYING file](COPYING) for the full license text. |