libgit2 bindings for Emacs

This is an experimental module for libgit2 bindings to Emacs, intended to boost the performance of magit.

Other work in this direction:

ksjogo/emacs-libgit2 in C, has been dormant for more than a year.
ubolonton/magit-libgit2 in Rust.

This module is written in C, and aims to be a thin wrapper around libgit2. That means that all functions in the libgit2 reference should translate more-or-less directly to Emacs, in the following sense:

Function names are the same, except with underscores replaced by hyphens. The prefix is changed from git- to libgit-.
Predicate functions are given a -p suffix, and words like "is" are removed, e.g. git_repository_is_bare becomes libgit-repository-bare-p.
Output parameters become return values.
Error codes become error signals (type giterr).
Return types map to their natural Emacs counterparts, or opaque user pointers when not applicable (e.g. for git-??? structures). Exceptions: git-oid and git-buf types are converted to Emacs strings.
Boolean parameters or pointers towards the end of argument lists whose natural default value is false or NULL will be made optional.

Quality-of-life convenience functionality is better implemented in Emacs Lisp than in C.

Building

There is a loader file written in Emacs Lisp that will build the module for you, but the git submodule steps need to be run manually.

git submodule init
git submodule update
mkdir build
cd build
cmake ..
make

If you're on OSX and using Macports, you may need to set CMAKE_PREFIX_PATH to avoid linking against the wrong libiconv. For example,

cmake -DCMAKE_PREFIX_PATH=/opt/local ..

Testing

Ensure that you have Cask installed.

cask install
cd build
make test

To see more output for debugging new tests you can specify more verbose output.

make test ARGS=-V

Using

Ensure that libgit.el is somewhere in your load path. Then

(require 'libgit)

If the dynamic module was not already built, you should be asked to do it manually.

If you use Borg, then use the following .gitmodules entry.

[submodule "libgit"]
    path = lib/libgit
    url = git@github.com:magit/libegit2.git
    build-step = make

Contributing

Adding a function

Find the section that the function belongs to (i.e. git_SECTION_xyz).
Create, if necessary, src/egit-SECTION.h and src/egit-SECTION.c.
In src/egit-SECTION.h, declare the function with EGIT_DEFUN. See existing headers for examples.
In src/egit-SECTION.c, document the function with EGIT_DOC. See existing files for examples.
In src/egit-SECTION.c, implement the function. See existing files for examples.
1. Always check argument types in the beginning. Use EGIT_ASSERT for this. These macros may return.
2. Then, extract the data needed from emacs_value. This may involve allocating buffers for strings.
3. Call the libgit2 backend function.
4. Free any memory you might need to free that was allocated in step 2.
5. Check the error code if applicable with EGIT_CHECK_ERROR. This macro may return.
6. Create return value and return.
In src/egit.c, create a DEFUN call in egit_init. You may need to include a new header.

Adding a type

Sometimes a struct of type git_??? may need to be returned to Emacs as an opaque user pointer. To do this, we use a wrapper structure with a type information tag.

Some objects expose data that belong to other objects. In many cases, libgit2 keeps reference-counts on these internally, but that's not always true. In particular, git_repository structs are not reference-counted (although the data-owning sub-objects like git_odb are). Neither are lightweight public structs like git_index_entry, git_diff_XYZ, etc. In these cases, the parent types must be reference-counted on our side, and the child types must keep a reference to the parent alive.

In src/egit.h, add an entry to the egit_type enum for the new type.
In src/egit.h add a new EGIT_ASSERT macro for the new type.
In src/egit.c add a new entry to the egit_finalize switch statement to free the structure. If the type is reference-counted, also add an entry to the decref switch statement.
In src/egit.c add a new entry to the egit_typeof switch statement.
In src/egit.c add a new type predicate by calling the TYPECHECKER macro.
In src/egit.c create a DEFUN call in egit_init for the type predicate.
In src/interface.h add two new symbols, libgit-TYPE-p and TYPE.
In src/interface.c initialize those symbols in the em_init function.

Returning opaque pointers to Emacs

To create a new user pointer, call egit_wrap with arguments:

The emacs_env*
The type tag
The pointer to wrap
The parent wrapper, if applicable (note: this is an egit_object*, not a git_XYZ*)

To return an existing user pointer (usually by grabbing the parent field of an egit_object*), just increase the reference count and use the EM_USER_PTR macro. Do not do this for types that are not reference-counted!

Function list

This is a complete list of functions in libgit2. It therefore serves more or less as an upper bound on the amount of work needed.

Legend:

:heavy_check_mark: Function is implemented
:x: Function should probably not be implemented (reason given)
:grey_question: Undecided

Some functions are defined in libgit2 headers in the sys subdirectory, and are not reachable from a standard include (i.e. #include "git2.h"). For now, we will skip those on the assumption that they are more specialized.

Estimates (updated periodically):

Implemented: 325 (41.8%)
Should not implement: 169 (21.7%)
To do: 284 (36.5%)
Total: 778

extra

These are functions that do not have a libgit2 equivalent.

Type checkers and predicates:

:heavy_check_mark: git-typeof
:heavy_check_mark: git-blame-p
:heavy_check_mark: git-commit-p
:heavy_check_mark: git-cred-p
:heavy_check_mark: git-diff-p
:heavy_check_mark: git-diff-delta-p
:heavy_check_mark: git-diff-binary-p
:heavy_check_mark: git-diff-hunk-p
:heavy_check_mark: git-diff-line-p
:heavy_check_mark: git-index-p
:heavy_check_mark: git-index-entry-p
:heavy_check_mark: git-object-p
:heavy_check_mark: git-reference-p
:heavy_check_mark: git-repository-p
:heavy_check_mark: git-signature-p
:heavy_check_mark: git-reference-direct-p
:heavy_check_mark: git-reference-symbolic-p
:heavy_check_mark: git-transaction-p
:heavy_check_mark: git-tree-p

Getters for public structs:

:heavy_check_mark: git-blame-hunk-commit-id
:heavy_check_mark: git-blame-hunk-lines
:heavy_check_mark: git-blame-hunk-orig-path
:heavy_check_mark: git-blame-hunk-signature
:heavy_check_mark: git-blame-hunk-start-line-number
:heavy_check_mark: git-diff-delta-file-id
:heavy_check_mark: git-diff-delta-file-path
:heavy_check_mark: git-diff-delta-nfiles
:heavy_check_mark: git-diff-delta-similarity
:heavy_check_mark: git-diff-delta-status
:heavy_check_mark: git-diff-delta-file-exists-p
:heavy_check_mark: git-diff-hunk-header
:heavy_check_mark: git-diff-hunk-lines
:heavy_check_mark: git-diff-hunk-start
:heavy_check_mark: git-diff-line-origin
:heavy_check_mark: git-diff-line-lineno
:heavy_check_mark: git-diff-line-content
:heavy_check_mark: git-index-entry-path
:heavy_check_mark: git-signature-name
:heavy_check_mark: git-signature-email
:heavy_check_mark: git-signature-time

Iterators converted to map functions:

:heavy_check_mark: git-branch-foreach
:heavy_check_mark: git-index-conflict-foreach

annotated

:x: git-annotated-commit-free (memory management shouldn't be exposed to Emacs)
:heavy_check_mark: git-annotated-commit-from-fetchhead
:heavy_check_mark: git-annotated-commit-from-ref
:heavy_check_mark: git-annotated-commit-from-revspec
:heavy_check_mark: git-annotated-commit-id
:heavy_check_mark: git-annotated-commit-lookup

attr

:grey_question: git-attr-add-macro
:grey_question: git-attr-cache-flush
:grey_question: git-attr-foreach
:grey_question: git-attr-get
:grey_question: git-attr-get-many
:grey_question: git-attr-value

blame

:grey_question: git-blame-buffer
:heavy_check_mark: git-blame-file
:x: git-blame-free (memory management shouldn't be exposed to Emacs)
:heavy_check_mark: git-blame-get-hunk-byindex
:heavy_check_mark: git-blame-get-hunk-byline
:heavy_check_mark: git-blame-get-hunk-count
:x: git-blame-init-options (options are represented by an alist)

blob

:heavy_check_mark: git-blob-create-frombuffer
:heavy_check_mark: git-blob-create-fromdisk
:grey_question: git-blob-create-fromstream
:grey_question: git-blob-create-fromstream-commit
:heavy_check_mark: git-blob-create-fromworkdir
:grey_question: git-blob-dup
:heavy_check_mark: git-blob-filtered-content
:x: git-blob-free (memory management shouldn't be exposed to Emacs)
:heavy_check_mark: git-blob-id
:heavy_check_mark: git-blob-is-binary (as libgit-blob-binary-p)
:heavy_check_mark: git-blob-lookup
:heavy_check_mark: git-blob-lookup-prefix
:heavy_check_mark: git-blob-owner
:heavy_check_mark: `git-blob-rawcont

Libegit2

Install / Use

README