This module provides a brief introductory tutorial in the "Introduction" section followed by a lengthy discussion of the library's design and idioms.

The gitlib library provides high-level types for working with the libgit2 C library (http://libgit2.github.com). The intention is to make libgit2 easier and more type-safe, while using laziness to avoid unnecessary work.

Every use of gitlib must begin with a Repository object. At the moment each Repository must be associated with a local directory, even if the Git objects are kept elsewhere via a custom backend (see https://github.com/libgit2/libgit2/issues/1213).

If no Repository exists yet, use createRepository; if one does exist, use openRepository; or, you can use openOrCreateRepository. For example:

repo <- openOrCreateRepository path False -- False here means "not bare"
... make use of the repository ...

If you are working with an existing repository, probably the first thing you'll want to do is resolve a reference so that you can lookup a commit:

repo   <- openOrCreateRepository path False
ref    <- resolveRef repo "HEAD"
commit <- maybe (return Nothing) (lookupCommit repo) ref

resolveRef works for both symbolic and specific refs. Further, this pattern is rather common, so there is a shortcut called lookupRefCommit. Or, if you have a SHA string, you can use lookupCommit with parseOid.

repo          <- openOrCreateRepository path False
commitFromRef <- lookupRefCommit repo "HEAD"             :: Maybe Commit
commitFromSHA <- lookupCommit repo (parseOid "f7acdbed") :: Maybe Commit

If you don't have a commit object, the recommend way to create one is by creating a Signature and using it to modify the return value from create. This requires a Repository object:

now <- getCurrentTime
let sig = Signature {
              signatureName  = "John Smith"
            , signatureEmail = "[email protected]"
            , signatureWhen  = now }
    c   = (createCommit repo) {
            , commitAuthor    = sig
            , commitCommitter = sig }
            

Load a Commit, and thereafter its history through its parents, or load a Tree or Blob from its contents.

1. Construct a new commit