libgit2 - the Git linkable library

| Build Status | | | ------------ | - | | main branch builds | | | v1.9 branch builds | | | v1.8 branch builds | | | Nightly builds | |

libgit2 is a portable, pure C implementation of the Git core methods provided as a linkable library with a solid API, allowing to build Git functionality into your application.

libgit2 is used in a variety of places, from GUI clients to hosting providers ("forges") and countless utilities and applications in between. Because it's written in C, it can be made available to any other programming language through "bindings", so you can use it in Ruby, .NET, Python, Node.js, Rust, and more.

libgit2 is licensed under a very permissive license (GPLv2 with a special Linking Exception). This means that you can link against the library with any kind of software without making that software fall under the GPL. Changes to libgit2 would still be covered under its GPL license.

Using libgit2
Quick Start
Getting Help
What It Can Do
Optional dependencies
Initialization
Threading
Conventions
Building libgit2 - Using CMake
Language Bindings
How Can I Contribute?
License

Using libgit2

Most of these instructions assume that you're writing an application in C and want to use libgit2 directly. If you're not using C, and you're writing in a different language or platform like .NET, Node.js, or Ruby, then there is probably a "language binding" that you can use to take care of the messy tasks of calling into native code.

But if you do want to use libgit2 directly - because you're building an application in C - then you may be able use an existing binary. There are packages for the vcpkg and conan package managers. And libgit2 is available in Homebrew and most Linux distributions.

However, these versions may be outdated and we recommend using the latest version if possible. Thankfully libgit2 is not hard to compile.

Quick Start

Prerequisites for building libgit2:

CMake, and is recommended to be installed into your PATH.
Python is used by our test framework, and should be installed into your PATH.
C compiler: libgit2 is C90 and should compile on most compilers.
- Windows: Visual Studio is recommended
- Mac: Xcode is recommended
- Unix: gcc or clang is recommended.

Build

Create a build directory beneath the libgit2 source directory, and change into it: mkdir build && cd build
Create the cmake build environment: cmake ..
Build libgit2: cmake --build .

Trouble with these steps? Read our troubleshooting guide. More detailed build guidance is available below.

Getting Help

Chat with us

via IRC: join #libgit2 on libera.
via Slack: visit slack.libgit2.org to sign up, then join us in #libgit2

Getting Help

If you have questions about the library, please be sure to check out the API documentation. If you still have questions, reach out to us on Slack or post a question on StackOverflow (with the libgit2 tag).

Reporting Bugs

Please open a GitHub Issue and include as much information as possible. If possible, provide sample code that illustrates the problem you're seeing. If you're seeing a bug only on a specific repository, please provide a link to it if possible.

We ask that you not open a GitHub Issue for help, only for bug reports.

Reporting Security Issues

Please have a look at SECURITY.md.

What It Can Do

libgit2 provides you with the ability to manage Git repositories in the programming language of your choice. It's used in production to power many applications including GitHub.com, Plastic SCM and Azure DevOps.

It does not aim to replace the git tool or its user-facing commands. Some APIs resemble the plumbing commands as those align closely with the concepts of the Git system, but most commands a user would type are out of scope for this library to implement directly.

The library provides:

SHA conversions, formatting and shortening
abstracted ODB backend system
commit, tag, tree and blob parsing, editing, and write-back
tree traversal
revision walking
index file (staging area) manipulation
reference management (including packed references)
config file management
high level repository management
thread safety and reentrancy
descriptive and detailed error messages
...and more (over 175 different API calls)

As libgit2 is purely a consumer of the Git system, we have to adjust to changes made upstream. This has two major consequences:

Some changes may require us to change provided interfaces. While we try to implement functions in a generic way so that no future changes are required, we cannot promise a completely stable API.
As we have to keep up with changes in behavior made upstream, we may lag behind in some areas. We usually to document these incompatibilities in our issue tracker with the label "git change".

Optional dependencies

While the library provides git functionality with very few dependencies, some recommended dependencies are used for performance or complete functionality.

Hash generation: Git uses SHA1DC (collision detecting SHA1) for its default hash generation. SHA256 support is experimental, and optimized support is provided by system libraries on macOS and Windows, or by the HTTPS library on Unix systems when available.
Threading: is provided by the system libraries on Windows, and pthreads on Unix systems.
HTTPS: is provided by the system libraries on macOS and Windows, or by OpenSSL or mbedTLS on other Unix systems.
SSH: is provided by libssh2 or by invoking OpenSSH.
Unicode: is provided by the system libraries on Windows and macOS.

Initialization

The library needs to keep track of some global state. Call

git_libgit2_init();

before calling any other libgit2 functions. You can call this function many times. A matching number of calls to

git_libgit2_shutdown();

will free the resources. Note that if you have worker threads, you should call git_libgit2_shutdown after those threads have exited. If you require assistance coordinating this, simply have the worker threads call git_libgit2_init at startup and git_libgit2_shutdown at shutdown.

Threading

See threading for information

Conventions

See conventions for an overview of the external and internal API/coding conventions we use.

Building libgit2 - Using CMake

Building

libgit2 builds cleanly on most platforms without any external dependencies as a requirement. libgit2 is built using CMake (version 2.8 or newer) on all platforms.

On most systems you can build the library using the following commands

$ mkdir build && cd build
$ cmake ..
$ cmake --build .

To include the

Libgit2

Install / Use

README