README.md 5.21 KB
Newer Older
Scott Chacon committed
1
libgit2 - the Git linkable library
2
======================
Scott Chacon committed
3

4 5
[![Build Status](https://secure.travis-ci.org/libgit2/libgit2.png?branch=development)](http://travis-ci.org/libgit2/libgit2)

Scott Chacon committed
6 7 8 9
libgit2 is a portable, pure C implementation of the Git core methods provided as a
re-entrant linkable library with a solid API, allowing you to write native
speed custom Git applications in any language with bindings.

10 11 12 13 14
libgit2 is licensed under a **very permissive license** (GPLv2 with a special Linking Exception).
This basically means that you can link it (unmodified) with any kind of software without having to
release its source code.

* Mailing list: <libgit2@librelist.org>
15
    * Archives: <http://librelist.com/browser/libgit2/>
Vicent Marti committed
16
* Website: <http://libgit2.github.com>
17
* API documentation: <http://libgit2.github.com/libgit2>
Vicent Marti committed
18
* Usage guide: <http://libgit2.github.com/api.html>
Scott Chacon committed
19 20 21 22 23

What It Can Do
==================================

libgit2 is already very usable.
24

25
* SHA conversions, formatting and shortening
26
* abstracted ODB backend system
Vicent Marti committed
27
* commit, tag, tree and blob parsing, editing, and write-back
Scott Chacon committed
28
* tree traversal
29 30 31
* revision walking
* index file (staging area) manipulation
* reference management (including packed references)
Vicent Marti committed
32 33 34 35 36
* config file management
* high level repository management
* thread safety and reentrancy
* descriptive and detailed error messages
* ...and more (over 175 different API calls)
37

Vicent Marti committed
38 39
Building libgit2 - Using CMake
==============================
Peter Drahoš committed
40

41
libgit2 builds cleanly on most platforms without any external dependencies.
42
Under Unix-like systems, like Linux, \*BSD and Mac OS X, libgit2 expects `pthreads` to be available;
43 44 45
they should be installed by default on all systems. Under Windows, libgit2 uses the native Windows API
for threading.

Vicent Marti committed
46
The libgit2 library is built using CMake 2.6+ (<http://www.cmake.org>) on all platforms.
Scott Chacon committed
47

Vicent Marti committed
48
On most systems you can build the library using the following commands
Scott Chacon committed
49

Vicent Marti committed
50 51 52
	$ mkdir build && cd build
	$ cmake ..
	$ cmake --build .
53

Vicent Marti committed
54 55 56
Alternatively you can point the CMake GUI tool to the CMakeLists.txt file and generate platform specific build project or IDE workspace.

To install the library you can specify the install prefix by setting:
Scott Chacon committed
57

Vicent Marti committed
58 59
	$ cmake .. -DCMAKE_INSTALL_PREFIX=/install/prefix
	$ cmake --build . --target install
Scott Chacon committed
60

61 62 63 64
If you want to build a universal binary for Mac OS X, CMake sets it
all up for you if you use `-DCMAKE_OSX_ARCHITECTURES="i386;x86_64"`
when configuring.

Vicent Marti committed
65
For more advanced use or questions about CMake please read <http://www.cmake.org/Wiki/CMake_FAQ>.
66

Vicent Marti committed
67 68 69
The following CMake variables are declared:

- `INSTALL_BIN`: Where to install binaries to.
70
- `LIB_INSTALL_DIR`: Where to install libraries to.
Vicent Marti committed
71
- `INSTALL_INC`: Where to install headers to.
72
- `BUILD_SHARED_LIBS`: Build libgit2 as a Shared Library (defaults to ON)
73
- `BUILD_CLAR`: Build [Clar](https://github.com/tanoku/clar)-based test suite (defaults to ON)
Vicent Marti committed
74
- `THREADSAFE`: Build libgit2 with threading support (defaults to OFF)
75

Vicent Marti committed
76 77
Language Bindings
==================================
Scott Chacon committed
78

Vicent Marti committed
79
Here are the bindings to libgit2 that are currently available:
Scott Chacon committed
80

81 82
* C++
    * libqgit2, Qt bindings <https://projects.kde.org/projects/playground/libs/libqgit2/>
83 84
* Chicken Scheme
    * chicken-git <https://wiki.call-cc.org/egg/git>
85 86 87 88 89 90 91
* Delphi
    * GitForDelphi <https://github.com/libgit2/GitForDelphi>
* Erlang
    * Geef <https://github.com/schacon/geef>
* Go
    * go-git <https://github.com/str1ngs/go-git>
* GObject
92
    * libgit2-glib <https://live.gnome.org/Libgit2-glib>
93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118
* Haskell
    * hgit2 <https://github.com/norm2782/hgit2>
* Lua
    * luagit2 <https://github.com/libgit2/luagit2>
* .NET
    * libgit2net, low level bindings <https://github.com/txdv/libgit2net>
    * libgit2sharp <https://github.com/libgit2/libgit2sharp>
* Node.js
    * node-gitteh <https://github.com/libgit2/node-gitteh>
    * nodegit <https://github.com/tbranyen/nodegit>
* Objective-C
    * objective-git <https://github.com/libgit2/objective-git>
* OCaml
    * libgit2-ocaml <https://github.com/burdges/libgit2-ocaml>
* Parrot Virtual Machine
    * parrot-libgit2 <https://github.com/letolabs/parrot-libgit2>
* Perl
    * git-xs-pm <https://github.com/ingydotnet/git-xs-pm>
* PHP
    * php-git <https://github.com/libgit2/php-git>
* Python
    * pygit2 <https://github.com/libgit2/pygit2>
* Ruby
    * Rugged <https://github.com/libgit2/rugged>
* Vala
    * libgit2.vapi <https://github.com/apmasell/vapis/blob/master/libgit2.vapi>
Scott Chacon committed
119 120 121 122

If you start another language binding to libgit2, please let us know so
we can add it to the list.

123
How Can I Contribute?
124 125 126
==================================

Fork libgit2/libgit2 on GitHub, add your improvement, push it to a branch
127
in your fork named for the topic, send a pull request. If you change the
128
API or make other large changes, make a note of it in docs/rel-notes/ in a
129
file named after the next release.
130 131 132 133 134 135 136

You can also file bugs or feature requests under the libgit2 project on
GitHub, or join us on the mailing list by sending an email to:

libgit2@librelist.com


137
License
Scott Chacon committed
138
==================================
Vicent Marti committed
139
libgit2 is under GPL2 **with linking exemption**. This means you
Scott Chacon committed
140 141 142 143 144
can link to the library with any program, commercial, open source or
other.  However, you cannot modify libgit2 and distribute it without
supplying the source.

See the COPYING file for the full license text.