Safe Haskell | Safe-Inferred |
---|
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 = "johnsmith@nowhere.org" , 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.
- Construct a new commit