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