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

4 5 6
| Build Status | |
| ------------ | - |
| **master** branch CI builds | [![Azure Pipelines Build Status](https://dev.azure.com/libgit2/libgit2/_apis/build/status/libgit2?branchName=master)](https://dev.azure.com/libgit2/libgit2/_build/latest?definitionId=7&branchName=master)   |
7
| **v1.0 branch** CI builds | [![Azure Pipelines Build Status](https://dev.azure.com/libgit2/libgit2/_apis/build/status/libgit2?branchName=maint/v1.0)](https://dev.azure.com/libgit2/libgit2/_build/latest?definitionId=7&branchName=maint/v1.0) |
8
| **v0.28 branch** CI builds | [![Azure Pipelines Build Status](https://dev.azure.com/libgit2/libgit2/_apis/build/status/libgit2?branchName=maint/v0.28)](https://dev.azure.com/libgit2/libgit2/_build/latest?definitionId=7&branchName=maint/v0.28) |
9
| **Nightly** builds | [![Azure Pipelines Build Status](https://libgit2.visualstudio.com/libgit2/_apis/build/status/nightly?branchName=master&label=Full+Build)](https://libgit2.visualstudio.com/libgit2/_build/latest?definitionId=9&branchName=master) [![Coverity Build Status](https://dev.azure.com/libgit2/libgit2/_apis/build/status/coverity?branchName=master&label=Coverity+Build)](https://dev.azure.com/libgit2/libgit2/_build/latest?definitionId=21?branchName=master) [![Coverity Scan Build Status](https://scan.coverity.com/projects/639/badge.svg)](https://scan.coverity.com/projects/639) |
10

11
`libgit2` is a portable, pure C implementation of the Git core methods
12 13 14 15 16 17 18 19 20 21 22 23
provided as a linkable library with a solid API, allowing to build Git
functionality into your application.  Language bindings like
[Rugged](https://github.com/libgit2/rugged) (Ruby),
[LibGit2Sharp](https://github.com/libgit2/libgit2sharp) (.NET),
[pygit2](http://www.pygit2.org/) (Python) and
[NodeGit](http://nodegit.org) (Node) allow you to build Git tooling
in your favorite language.

`libgit2` is used to power Git GUI clients like
[GitKraken](https://gitkraken.com/) and [gmaster](https://gmaster.io/)
and on Git hosting providers like [GitHub](https://github.com/),
[GitLab](https://gitlab.com/) and
24
[Azure DevOps](https://azure.com/devops).
25
We perform the merge every time you click "merge pull request".
Scott Chacon committed
26

27 28 29 30 31
`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.
Additionally, the example code has been released to the public domain (see the
[separate license](examples/COPYING) for more information).
32

33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49
Table of Contents
=================

* [Quick Start](#quick-start)
* [Getting Help](#getting-help)
* [What It Can Do](#what-it-can-do)
* [Optional dependencies](#optional-dependencies)
* [Initialization](#initialization)
* [Threading](#threading)
* [Conventions](#conventions)
* [Building libgit2 - Using CMake](#building-libgit2---using-cmake)
    * [Building](#building)
    * [Installation](#installation)
    * [Advanced Usage](#advanced-usage)
    * [Compiler and linker options](#compiler-and-linker-options)
    * [MacOS X](#macos-x)
    * [Android](#android)
A-Ovchinnikov-mx committed
50
    * [MinGW](#mingw)
51 52 53 54
* [Language Bindings](#language-bindings)
* [How Can I Contribute?](#how-can-i-contribute)
* [License](#license)

55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75
Quick Start
===========

**Prerequisites** for building libgit2:

1. [CMake](https://cmake.org/), and is recommended to be installed into
   your `PATH`.
2. [Python](https://www.python.org) is used by our test framework, and
   should be installed into your `PATH`.
3. 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**

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

Eric Huss committed
76
Trouble with these steps?  Read our [troubleshooting guide](docs/troubleshooting.md).
77
More detailed build guidance is available below.
78

79 80
Getting Help
============
81

82
**Chat with us**
83

84 85 86
- via IRC: join [#libgit2](https://webchat.freenode.net/#libgit2) on Freenode
- via Slack: visit [slack.libgit2.org](http://slack.libgit2.org/) to sign up,
  then join us in `#libgit2`
87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102

**Getting Help**

If you have questions about the library, please be sure to check out the
[API documentation](http://libgit2.github.com/libgit2/).  If you still have
questions, reach out to us on Slack or post a question on 
[StackOverflow](http://stackoverflow.com/questions/tagged/libgit2) (with the `libgit2` tag).

**Reporting Bugs**

Please open a [GitHub Issue](https://github.com/libgit2/libgit2/issues) 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.
Scott Chacon committed
103

104 105
**Reporting Security Issues**

106
Please have a look at SECURITY.md.
107

Scott Chacon committed
108
What It Can Do
109
==============
Scott Chacon committed
110

111 112
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
113
applications including GitHub.com, Plastic SCM and Azure DevOps.
114 115 116 117 118 119 120

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:
121

122
* SHA conversions, formatting and shortening
123
* abstracted ODB backend system
Vicent Marti committed
124
* commit, tag, tree and blob parsing, editing, and write-back
Scott Chacon committed
125
* tree traversal
126 127 128
* revision walking
* index file (staging area) manipulation
* reference management (including packed references)
Vicent Marti committed
129 130 131 132 133
* config file management
* high level repository management
* thread safety and reentrancy
* descriptive and detailed error messages
* ...and more (over 175 different API calls)
134

135 136 137 138 139 140 141 142 143 144
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".

145 146 147 148 149 150 151 152
Optional dependencies
=====================

While the library provides git functionality without the need for
dependencies, it can make use of a few libraries to add to it:

- pthreads (non-Windows) to enable threadsafe access as well as multi-threaded pack generation
- OpenSSL (non-Windows) to talk over HTTPS and provide the SHA-1 functions
Linquize committed
153
- LibSSH2 to enable the SSH transport
154 155
- iconv (OSX) to handle the HFS+ path encoding peculiarities

156 157 158 159 160 161 162 163 164 165 166
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();

167 168 169 170
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.
171

172 173 174
Threading
=========

175
See [threading](docs/threading.md) for information
176

177 178 179
Conventions
===========

180
See [conventions](docs/conventions.md) for an overview of the external
181 182
and internal API/coding conventions we use.

Vicent Marti committed
183 184
Building libgit2 - Using CMake
==============================
Peter Drahoš committed
185

186 187 188
Building
--------

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

194
The `libgit2` library is built using [CMake](<https://cmake.org/>) (version 2.8 or newer) on all platforms.
Scott Chacon committed
195

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

Vicent Marti committed
198 199 200
	$ mkdir build && cd build
	$ cmake ..
	$ cmake --build .
201

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

204 205 206
Running Tests
-------------

207 208
Once built, you can run the tests from the `build` directory with the command

209
	$ ctest -V
210 211 212 213 214

Alternatively you can run the test suite directly using,

	$ ./libgit2_clar

215 216 217 218 219 220 221
Invoking the test suite directly is useful because it allows you to execute
individual tests, or groups of tests using the `-s` flag.  For example, to
run the index tests:

    $ ./libgit2_clar -sindex

To run a single test named `index::racy::diff`, which corresponds to the test
222
function [`test_index_racy__diff`](https://github.com/libgit2/libgit2/blob/master/tests/index/racy.c#L23):
223 224 225

    $ ./libgit2_clar -sindex::racy::diff

226 227 228 229 230 231 232 233 234 235
The test suite will print a `.` for every passing test, and an `F` for any
failing test.  An `S` indicates that a test was skipped because it is not
applicable to your platform or is particularly expensive.

**Note:** There should be _no_ failing tests when you build an unmodified
source tree from a [release](https://github.com/libgit2/libgit2/releases),
or from the [master branch](https://github.com/libgit2/libgit2/tree/master).
Please contact us or [open an issue](https://github.com/libgit2/libgit2/issues)
if you see test failures.

236 237 238
Installation
------------

Vicent Marti committed
239
To install the library you can specify the install prefix by setting:
Scott Chacon committed
240

Vicent Marti committed
241 242
	$ cmake .. -DCMAKE_INSTALL_PREFIX=/install/prefix
	$ cmake --build . --target install
Scott Chacon committed
243

244 245 246
Advanced Usage
--------------

247
For more advanced use or questions about CMake please read <https://cmake.org/Wiki/CMake_FAQ>.
248

Vicent Marti committed
249 250
The following CMake variables are declared:

251 252 253
- `CMAKE_INSTALL_BINDIR`: Where to install binaries to.
- `CMAKE_INSTALL_LIBDIR`: Where to install libraries to.
- `CMAKE_INSTALL_INCLUDEDIR`: Where to install headers to.
254
- `BUILD_SHARED_LIBS`: Build libgit2 as a Shared Library (defaults to ON)
Keith Dahlby committed
255
- `BUILD_CLAR`: Build [Clar](https://github.com/vmg/clar)-based test suite (defaults to ON)
256
- `THREADSAFE`: Build libgit2 with threading support (defaults to ON)
257

258 259 260 261 262 263 264 265 266
To list all build options and their current value, you can do the
following:

	# Create and set up a build directory
	$ mkdir build
	$ cmake ..
	# List all build options and their values
	$ cmake -L

267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285
Compiler and linker options
---------------------------

CMake lets you specify a few variables to control the behavior of the
compiler and linker. These flags are rarely used but can be useful for
64-bit to 32-bit cross-compilation.

- `CMAKE_C_FLAGS`: Set your own compiler flags
- `CMAKE_FIND_ROOT_PATH`: Override the search path for libraries
- `ZLIB_LIBRARY`, `OPENSSL_SSL_LIBRARY` AND `OPENSSL_CRYPTO_LIBRARY`:
Tell CMake where to find those specific libraries

MacOS X
-------

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.

286 287 288 289
Android
-------

Extract toolchain from NDK using, `make-standalone-toolchain.sh` script.
Nicolas Kaiser committed
290 291
Optionally, crosscompile and install OpenSSL inside of it. Then create CMake
toolchain file that configures paths to your crosscompiler (substitute `{PATH}`
292 293 294 295
with full path to the toolchain):

	SET(CMAKE_SYSTEM_NAME Linux)
	SET(CMAKE_SYSTEM_VERSION Android)
nulltoken committed
296

297 298 299
	SET(CMAKE_C_COMPILER   {PATH}/bin/arm-linux-androideabi-gcc)
	SET(CMAKE_CXX_COMPILER {PATH}/bin/arm-linux-androideabi-g++)
	SET(CMAKE_FIND_ROOT_PATH {PATH}/sysroot/)
nulltoken committed
300

301 302 303 304
	SET(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
	SET(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
	SET(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)

305
Add `-DCMAKE_TOOLCHAIN_FILE={pathToToolchainFile}` to cmake command
306 307
when configuring.

A-Ovchinnikov-mx committed
308 309 310 311 312 313 314 315 316 317 318 319 320 321
MinGW
-----

If you want to build the library in MinGW environment with SSH support enabled,
you may need to pass `-DCMAKE_LIBRARY_PATH="${MINGW_PREFIX}/${MINGW_CHOST}/lib/"` flag
to CMake when configuring. This is because CMake cannot find the Win32 libraries in
MinGW folders by default and you might see an error message stating that CMake
could not resolve `ws2_32` library during configuration.

Another option would be to install `msys2-w32api-runtime` package before configuring.
This package installs the Win32 libraries into `/usr/lib` folder which is by default
recognized as the library path by CMake. Please note though that this package is meant
for MSYS subsystem which is different from MinGW.

Vicent Marti committed
322 323
Language Bindings
==================================
Scott Chacon committed
324

Vicent Marti committed
325
Here are the bindings to libgit2 that are currently available:
Scott Chacon committed
326

327
* C++
328
    * libqgit2, Qt bindings <https://projects.kde.org/projects/playground/libs/libqgit2/repository/>
329 330
* Chicken Scheme
    * chicken-git <https://wiki.call-cc.org/egg/git>
331
* D
Morton Fox committed
332
    * dlibgit <https://github.com/s-ludwig/dlibgit>
333 334 335
* Delphi
    * GitForDelphi <https://github.com/libgit2/GitForDelphi>
* Erlang
336
    * Geef <https://github.com/carlosmn/geef>
337
* Go
338
    * git2go <https://github.com/libgit2/git2go>
339
* GObject
340
    * libgit2-glib <https://wiki.gnome.org/Projects/Libgit2-glib>
341 342
* Guile
	* Guile-Git <https://gitlab.com/guile-git/guile-git>
343
* Haskell
344
    * hgit2 <https://github.com/jwiegley/gitlib>
345 346
* Java
    * Jagged <https://github.com/ethomson/jagged>
347 348
* Javascript / WebAssembly ( browser and nodejs )
    * WASM-git <https://github.com/petersalomonsen/wasm-git>
349
* Julia
350
    * LibGit2.jl <https://github.com/JuliaLang/julia/tree/master/stdlib/LibGit2>
351 352 353 354 355
* Lua
    * luagit2 <https://github.com/libgit2/luagit2>
* .NET
    * libgit2sharp <https://github.com/libgit2/libgit2sharp>
* Node.js
356
    * nodegit <https://github.com/nodegit/nodegit>
357 358 359
* Objective-C
    * objective-git <https://github.com/libgit2/objective-git>
* OCaml
360
    * ocaml-libgit2 <https://github.com/fxfactorial/ocaml-libgit2>
361 362 363
* Parrot Virtual Machine
    * parrot-libgit2 <https://github.com/letolabs/parrot-libgit2>
* Perl
364
    * Git-Raw <https://github.com/jacquesg/p5-Git-Raw>
365 366
* PHP
    * php-git <https://github.com/libgit2/php-git>
367
* PowerShell
368
    * PSGit <https://github.com/PoshCode/PSGit>
369 370
* Python
    * pygit2 <https://github.com/libgit2/pygit2>
371 372
* R
    * git2r <https://github.com/ropensci/git2r>
373 374
* Ruby
    * Rugged <https://github.com/libgit2/rugged>
375
* Rust
Dominik Ritter committed
376
    * git2-rs <https://github.com/rust-lang/git2-rs>
377
* Swift
378
    * SwiftGit2 <https://github.com/SwiftGit2/SwiftGit2>
379 380
* Vala
    * libgit2.vapi <https://github.com/apmasell/vapis/blob/master/libgit2.vapi>
Scott Chacon committed
381 382 383 384

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

385
How Can I Contribute?
386 387
==================================

388 389 390 391 392
We welcome new contributors!  We have a number of issues marked as
["up for grabs"](https://github.com/libgit2/libgit2/issues?q=is%3Aissue+is%3Aopen+label%3A%22up+for+grabs%22)
and
["easy fix"](https://github.com/libgit2/libgit2/issues?utf8=✓&q=is%3Aissue+is%3Aopen+label%3A%22easy+fix%22)
that are good places to jump in and get started.  There's much more detailed
393
information in our list of [outstanding projects](docs/projects.md).
394

395 396
Please be sure to check the [contribution guidelines](docs/contributing.md) to
understand our workflow, and the libgit2 [coding conventions](docs/conventions.md).
397

398
License
Scott Chacon committed
399
==================================
400

SeijiIto committed
401
`libgit2` is under GPL2 **with linking exception**. This means you can link to
402
and use the library from any program, proprietary or open source; paid or
403 404
gratis.  However, if you modify libgit2 itself, you must distribute the
source to your modified version of libgit2.
Scott Chacon committed
405

406
See the [COPYING file](COPYING) for the full license text.