Blame README.md

Packit Service 20376f
libgit2 - the Git linkable library
Packit Service 20376f
==================================
Packit Service 20376f
Packit Service 20376f
[![Azure Pipelines Build Status](https://dev.azure.com/libgit2/libgit2/_apis/build/status/libgit2)](https://dev.azure.com/libgit2/libgit2/_build/latest?definitionId=7)
Packit Service 20376f
[![Coverity Scan Build Status](https://scan.coverity.com/projects/639/badge.svg)](https://scan.coverity.com/projects/639)
Packit Service 20376f
Packit Service 20376f
`libgit2` is a portable, pure C implementation of the Git core methods
Packit Service 20376f
provided as a re-entrant linkable library with a solid API, allowing you to
Packit Service 20376f
write native speed custom Git applications in any language with bindings.
Packit Service 20376f
Packit Service 20376f
`libgit2` is licensed under a **very permissive license** (GPLv2 with a special
Packit Service 20376f
Linking Exception).  This basically means that you can link it (unmodified)
Packit Service 20376f
with any kind of software without having to release its source code.
Packit Service 20376f
Additionally, the example code has been released to the public domain (see the
Packit Service 20376f
[separate license](examples/COPYING) for more information).
Packit Service 20376f
Packit Service 20376f
Getting Help
Packit Service 20376f
============
Packit Service 20376f
Packit Service 20376f
**Join us on Slack**
Packit Service 20376f
Packit Service 20376f
Visit [slack.libgit2.org](http://slack.libgit2.org/) to sign up, then join
Packit Service 20376f
us in `#libgit2`.  If you prefer IRC, you can also point your client to our
Packit Service 20376f
slack channel once you've registered.
Packit Service 20376f
Packit Service 20376f
**Getting Help**
Packit Service 20376f
Packit Service 20376f
If you have questions about the library, please be sure to check out the
Packit Service 20376f
[API documentation](http://libgit2.github.com/libgit2/).  If you still have
Packit Service 20376f
questions, reach out to us on Slack or post a question on 
Packit Service 20376f
[StackOverflow](http://stackoverflow.com/questions/tagged/libgit2) (with the `libgit2` tag).
Packit Service 20376f
Packit Service 20376f
**Reporting Bugs**
Packit Service 20376f
Packit Service 20376f
Please open a [GitHub Issue](https://github.com/libgit2/libgit2/issues) and
Packit Service 20376f
include as much information as possible.  If possible, provide sample code
Packit Service 20376f
that illustrates the problem you're seeing.  If you're seeing a bug only
Packit Service 20376f
on a specific repository, please provide a link to it if possible.
Packit Service 20376f
Packit Service 20376f
We ask that you not open a GitHub Issue for help, only for bug reports.
Packit Service 20376f
Packit Service 20376f
What It Can Do
Packit Service 20376f
==============
Packit Service 20376f
Packit Service 20376f
libgit2 provides you with the ability to manage Git repositories in the
Packit Service 20376f
programming language of your choice.  It's used in production to power many
Packit Service 20376f
applications including GitHub.com, Plastic SCM and Azure DevOps.
Packit Service 20376f
Packit Service 20376f
It does not aim to replace the git tool or its user-facing commands. Some APIs
Packit Service 20376f
resemble the plumbing commands as those align closely with the concepts of the
Packit Service 20376f
Git system, but most commands a user would type are out of scope for this
Packit Service 20376f
library to implement directly.
Packit Service 20376f
Packit Service 20376f
The library provides:
Packit Service 20376f
Packit Service 20376f
* SHA conversions, formatting and shortening
Packit Service 20376f
* abstracted ODB backend system
Packit Service 20376f
* commit, tag, tree and blob parsing, editing, and write-back
Packit Service 20376f
* tree traversal
Packit Service 20376f
* revision walking
Packit Service 20376f
* index file (staging area) manipulation
Packit Service 20376f
* reference management (including packed references)
Packit Service 20376f
* config file management
Packit Service 20376f
* high level repository management
Packit Service 20376f
* thread safety and reentrancy
Packit Service 20376f
* descriptive and detailed error messages
Packit Service 20376f
* ...and more (over 175 different API calls)
Packit Service 20376f
Packit Service 20376f
As libgit2 is purely a consumer of the Git system, we have to
Packit Service 20376f
adjust to changes made upstream. This has two major consequences:
Packit Service 20376f
Packit Service 20376f
* Some changes may require us to change provided interfaces. While we try to
Packit Service 20376f
  implement functions in a generic way so that no future changes are required,
Packit Service 20376f
  we cannot promise a completely stable API.
Packit Service 20376f
* As we have to keep up with changes in behavior made upstream, we may lag
Packit Service 20376f
  behind in some areas. We usually to document these incompatibilities in our
Packit Service 20376f
  issue tracker with the label "git change".
Packit Service 20376f
Packit Service 20376f
Optional dependencies
Packit Service 20376f
=====================
Packit Service 20376f
Packit Service 20376f
While the library provides git functionality without the need for
Packit Service 20376f
dependencies, it can make use of a few libraries to add to it:
Packit Service 20376f
Packit Service 20376f
- pthreads (non-Windows) to enable threadsafe access as well as multi-threaded pack generation
Packit Service 20376f
- OpenSSL (non-Windows) to talk over HTTPS and provide the SHA-1 functions
Packit Service 20376f
- LibSSH2 to enable the SSH transport
Packit Service 20376f
- iconv (OSX) to handle the HFS+ path encoding peculiarities
Packit Service 20376f
Packit Service 20376f
Initialization
Packit Service 20376f
===============
Packit Service 20376f
Packit Service 20376f
The library needs to keep track of some global state. Call
Packit Service 20376f
Packit Service 20376f
    git_libgit2_init();
Packit Service 20376f
Packit Service 20376f
before calling any other libgit2 functions. You can call this function many times. A matching number of calls to
Packit Service 20376f
Packit Service 20376f
    git_libgit2_shutdown();
Packit Service 20376f
Packit Service 20376f
will free the resources.  Note that if you have worker threads, you should
Packit Service 20376f
call `git_libgit2_shutdown` *after* those threads have exited.  If you
Packit Service 20376f
require assistance coordinating this, simply have the worker threads call
Packit Service 20376f
`git_libgit2_init` at startup and `git_libgit2_shutdown` at shutdown.
Packit Service 20376f
Packit Service 20376f
Threading
Packit Service 20376f
=========
Packit Service 20376f
Packit Service 20376f
See [THREADING](THREADING.md) for information
Packit Service 20376f
Packit Service 20376f
Conventions
Packit Service 20376f
===========
Packit Service 20376f
Packit Service 20376f
See [CONVENTIONS](CONVENTIONS.md) for an overview of the external
Packit Service 20376f
and internal API/coding conventions we use.
Packit Service 20376f
Packit Service 20376f
Building libgit2 - Using CMake
Packit Service 20376f
==============================
Packit Service 20376f
Packit Service 20376f
`libgit2` builds cleanly on most platforms without any external dependencies.
Packit Service 20376f
Under Unix-like systems, like Linux, \*BSD and Mac OS X, libgit2 expects `pthreads` to be available;
Packit Service 20376f
they should be installed by default on all systems. Under Windows, libgit2 uses the native Windows API
Packit Service 20376f
for threading.
Packit Service 20376f
Packit Service 20376f
The `libgit2` library is built using [CMake](<https://cmake.org/>) (version 2.8 or newer) on all platforms.
Packit Service 20376f
Packit Service 20376f
On most systems you can build the library using the following commands
Packit Service 20376f
Packit Service 20376f
	$ mkdir build && cd build
Packit Service 20376f
	$ cmake ..
Packit Service 20376f
	$ cmake --build .
Packit Service 20376f
Packit Service 20376f
Alternatively you can point the CMake GUI tool to the CMakeLists.txt file and generate platform specific build project or IDE workspace.
Packit Service 20376f
Packit Service 20376f
Once built, you can run the tests from the `build` directory with the command
Packit Service 20376f
Packit Service 20376f
	$ make test
Packit Service 20376f
Packit Service 20376f
Alternatively you can run the test suite directly using,
Packit Service 20376f
Packit Service 20376f
	$ ./libgit2_clar
Packit Service 20376f
Packit Service 20376f
To install the library you can specify the install prefix by setting:
Packit Service 20376f
Packit Service 20376f
	$ cmake .. -DCMAKE_INSTALL_PREFIX=/install/prefix
Packit Service 20376f
	$ cmake --build . --target install
Packit Service 20376f
Packit Service 20376f
For more advanced use or questions about CMake please read <https://cmake.org/Wiki/CMake_FAQ>.
Packit Service 20376f
Packit Service 20376f
The following CMake variables are declared:
Packit Service 20376f
Packit Service 20376f
- `BIN_INSTALL_DIR`: Where to install binaries to.
Packit Service 20376f
- `LIB_INSTALL_DIR`: Where to install libraries to.
Packit Service 20376f
- `INCLUDE_INSTALL_DIR`: Where to install headers to.
Packit Service 20376f
- `BUILD_SHARED_LIBS`: Build libgit2 as a Shared Library (defaults to ON)
Packit Service 20376f
- `BUILD_CLAR`: Build [Clar](https://github.com/vmg/clar)-based test suite (defaults to ON)
Packit Service 20376f
- `THREADSAFE`: Build libgit2 with threading support (defaults to ON)
Packit Service 20376f
- `STDCALL`: Build libgit2 as `stdcall`. Turn off for `cdecl` (Windows; defaults to ON)
Packit Service 20376f
Packit Service 20376f
Compiler and linker options
Packit Service 20376f
---------------------------
Packit Service 20376f
Packit Service 20376f
CMake lets you specify a few variables to control the behavior of the
Packit Service 20376f
compiler and linker. These flags are rarely used but can be useful for
Packit Service 20376f
64-bit to 32-bit cross-compilation.
Packit Service 20376f
Packit Service 20376f
- `CMAKE_C_FLAGS`: Set your own compiler flags
Packit Service 20376f
- `CMAKE_FIND_ROOT_PATH`: Override the search path for libraries
Packit Service 20376f
- `ZLIB_LIBRARY`, `OPENSSL_SSL_LIBRARY` AND `OPENSSL_CRYPTO_LIBRARY`:
Packit Service 20376f
Tell CMake where to find those specific libraries
Packit Service 20376f
Packit Service 20376f
MacOS X
Packit Service 20376f
-------
Packit Service 20376f
Packit Service 20376f
If you want to build a universal binary for Mac OS X, CMake sets it
Packit Service 20376f
all up for you if you use `-DCMAKE_OSX_ARCHITECTURES="i386;x86_64"`
Packit Service 20376f
when configuring.
Packit Service 20376f
Packit Service 20376f
Windows
Packit Service 20376f
-------
Packit Service 20376f
Packit Service 20376f
You need to run the CMake commands from the Visual Studio command
Packit Service 20376f
prompt, not the regular or Windows SDK one. Select the right generator
Packit Service 20376f
for your version with the `-G "Visual Studio X" option.
Packit Service 20376f
Packit Service 20376f
See [the website](http://libgit2.github.com/docs/guides/build-and-link/)
Packit Service 20376f
for more detailed instructions.
Packit Service 20376f
Packit Service 20376f
Android
Packit Service 20376f
-------
Packit Service 20376f
Packit Service 20376f
Extract toolchain from NDK using, `make-standalone-toolchain.sh` script.
Packit Service 20376f
Optionally, crosscompile and install OpenSSL inside of it. Then create CMake
Packit Service 20376f
toolchain file that configures paths to your crosscompiler (substitute `{PATH}`
Packit Service 20376f
with full path to the toolchain):
Packit Service 20376f
Packit Service 20376f
	SET(CMAKE_SYSTEM_NAME Linux)
Packit Service 20376f
	SET(CMAKE_SYSTEM_VERSION Android)
Packit Service 20376f
Packit Service 20376f
	SET(CMAKE_C_COMPILER   {PATH}/bin/arm-linux-androideabi-gcc)
Packit Service 20376f
	SET(CMAKE_CXX_COMPILER {PATH}/bin/arm-linux-androideabi-g++)
Packit Service 20376f
	SET(CMAKE_FIND_ROOT_PATH {PATH}/sysroot/)
Packit Service 20376f
Packit Service 20376f
	SET(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
Packit Service 20376f
	SET(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
Packit Service 20376f
	SET(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
Packit Service 20376f
Packit Service 20376f
Add `-DCMAKE_TOOLCHAIN_FILE={pathToToolchainFile}` to cmake command
Packit Service 20376f
when configuring.
Packit Service 20376f
Packit Service 20376f
Language Bindings
Packit Service 20376f
==================================
Packit Service 20376f
Packit Service 20376f
Here are the bindings to libgit2 that are currently available:
Packit Service 20376f
Packit Service 20376f
* C++
Packit Service 20376f
    * libqgit2, Qt bindings <https://projects.kde.org/projects/playground/libs/libqgit2/repository/>
Packit Service 20376f
* Chicken Scheme
Packit Service 20376f
    * chicken-git <https://wiki.call-cc.org/egg/git>
Packit Service 20376f
* D
Packit Service 20376f
    * dlibgit <https://github.com/s-ludwig/dlibgit>
Packit Service 20376f
* Delphi
Packit Service 20376f
    * GitForDelphi <https://github.com/libgit2/GitForDelphi>
Packit Service 20376f
* Erlang
Packit Service 20376f
    * Geef <https://github.com/carlosmn/geef>
Packit Service 20376f
* Go
Packit Service 20376f
    * git2go <https://github.com/libgit2/git2go>
Packit Service 20376f
* GObject
Packit Service 20376f
    * libgit2-glib <https://wiki.gnome.org/Projects/Libgit2-glib>
Packit Service 20376f
* Haskell
Packit Service 20376f
    * hgit2 <https://github.com/jwiegley/gitlib>
Packit Service 20376f
* Java
Packit Service 20376f
    * Jagged <https://github.com/ethomson/jagged>
Packit Service 20376f
* Julia
Packit Service 20376f
    * LibGit2.jl <https://github.com/jakebolewski/LibGit2.jl>
Packit Service 20376f
* Lua
Packit Service 20376f
    * luagit2 <https://github.com/libgit2/luagit2>
Packit Service 20376f
* .NET
Packit Service 20376f
    * libgit2sharp <https://github.com/libgit2/libgit2sharp>
Packit Service 20376f
* Node.js
Packit Service 20376f
    * nodegit <https://github.com/nodegit/nodegit>
Packit Service 20376f
* Objective-C
Packit Service 20376f
    * objective-git <https://github.com/libgit2/objective-git>
Packit Service 20376f
* OCaml
Packit Service 20376f
    * ocaml-libgit2 <https://github.com/fxfactorial/ocaml-libgit2>
Packit Service 20376f
* Parrot Virtual Machine
Packit Service 20376f
    * parrot-libgit2 <https://github.com/letolabs/parrot-libgit2>
Packit Service 20376f
* Perl
Packit Service 20376f
    * Git-Raw <https://github.com/jacquesg/p5-Git-Raw>
Packit Service 20376f
* PHP
Packit Service 20376f
    * php-git <https://github.com/libgit2/php-git>
Packit Service 20376f
* PowerShell
Packit Service 20376f
    * PSGit <https://github.com/PoshCode/PSGit>
Packit Service 20376f
* Python
Packit Service 20376f
    * pygit2 <https://github.com/libgit2/pygit2>
Packit Service 20376f
* R
Packit Service 20376f
    * git2r <https://github.com/ropensci/git2r>
Packit Service 20376f
* Ruby
Packit Service 20376f
    * Rugged <https://github.com/libgit2/rugged>
Packit Service 20376f
* Rust
Packit Service 20376f
    * git2-rs <https://github.com/alexcrichton/git2-rs>
Packit Service 20376f
* Swift
Packit Service 20376f
    * SwiftGit2 <https://github.com/SwiftGit2/SwiftGit2>
Packit Service 20376f
* Vala
Packit Service 20376f
    * libgit2.vapi <https://github.com/apmasell/vapis/blob/master/libgit2.vapi>
Packit Service 20376f
Packit Service 20376f
If you start another language binding to libgit2, please let us know so
Packit Service 20376f
we can add it to the list.
Packit Service 20376f
Packit Service 20376f
How Can I Contribute?
Packit Service 20376f
==================================
Packit Service 20376f
Packit Service 20376f
We welcome new contributors!  We have a number of issues marked as
Packit Service 20376f
["up for grabs"](https://github.com/libgit2/libgit2/issues?q=is%3Aissue+is%3Aopen+label%3A%22up+for+grabs%22)
Packit Service 20376f
and
Packit Service 20376f
["easy fix"](https://github.com/libgit2/libgit2/issues?utf8=✓&q=is%3Aissue+is%3Aopen+label%3A%22easy+fix%22)
Packit Service 20376f
that are good places to jump in and get started.  There's much more detailed
Packit Service 20376f
information in our list of [outstanding projects](PROJECTS.md).
Packit Service 20376f
Packit Service 20376f
Please be sure to check the [contribution guidelines](CONTRIBUTING.md) to
Packit Service 20376f
understand our workflow, and the libgit2 [coding conventions](CONVENTIONS.md).
Packit Service 20376f
Packit Service 20376f
License
Packit Service 20376f
==================================
Packit Service 20376f
Packit Service 20376f
`libgit2` is under GPL2 **with linking exception**. This means you can link to
Packit Service 20376f
and use the library from any program, proprietary or open source; paid or
Packit Service 20376f
gratis.  However, if you modify libgit2 itself, you must distribute the
Packit Service 20376f
source to your modified version of libgit2.
Packit Service 20376f
Packit Service 20376f
See the [COPYING file](COPYING) for the full license text.