Git.Tutorial

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

Introduction

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.

Repositories

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 ...

Note that the path variable here is of type FilePath, since gitlib almost never uses the String type.

References

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

Commits

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 = "[e-mail]"
             , 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