libghc-gitlib-doc 2.2.0.0-1build3 / usr / share / doc / libghc-gitlib-doc / html / gitlib.txt

-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | API library for working with Git repositories
--   
--   <tt>gitlib</tt> is a high-level, lazy and conduit-aware set of
--   abstractions for programming with Git types. Several different
--   backends are available, including one for the libgit2 C library
--   (<a>http://libgit2.github.com</a>) (see <tt>gitlib-libgit2</tt>). The
--   aim is both type-safety and convenience of use for Haskell users,
--   combined with high performance and minimal memory footprint by taking
--   advantage of Haskell's laziness and the conduit library's
--   deterministic resource cleanup.
--   
--   For further information, as well as typical use cases, see
--   <a>Git.Tutorial</a>.
@package gitlib
@version 2.2.0.0


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

module Git.Types
type RawFilePath = ByteString
data RepositoryFacts
RepositoryFacts :: !Bool -> RepositoryFacts
hasSymbolicReferences :: RepositoryFacts -> !Bool
type MonadGit m = (Failure GitException m, Applicative m, MonadIO m, MonadBaseControl IO m)
type RefName = Text
type CommitAuthor = Text
type CommitEmail = Text
type CommitMessage = Text
type TreeFilePath = RawFilePath

-- | <a>Repository</a> is the central point of contact between user code
--   and Git data objects. Every object must belong to some repository.
class (Applicative m, Monad m, Failure GitException m, IsOid (Oid m)) => Repository m where type family Oid m :: * data family Tree m :: * data family Options m :: *
facts :: Repository m => m RepositoryFacts
parseOid :: Repository m => Text -> m (Oid m)
deleteRepository :: Repository m => m ()
createReference :: Repository m => RefName -> RefTarget m -> m ()
lookupReference :: Repository m => RefName -> m (Maybe (RefTarget m))
updateReference :: Repository m => RefName -> RefTarget m -> m ()
deleteReference :: Repository m => RefName -> m ()
listReferences :: Repository m => m [RefName]
lookupCommit :: Repository m => CommitOid m -> m (Commit m)
lookupTree :: Repository m => TreeOid m -> m (Tree m)
lookupBlob :: Repository m => BlobOid m -> m (Blob m)
lookupTag :: Repository m => TagOid m -> m (Tag m)
lookupObject :: Repository m => Oid m -> m (Object m)
existsObject :: Repository m => Oid m -> m Bool
sourceObjects :: Repository m => Maybe (CommitOid m) -> CommitOid m -> Bool -> Producer m (ObjectOid m)
newTreeBuilder :: Repository m => Maybe (Tree m) -> m (TreeBuilder m)
treeOid :: Repository m => Tree m -> TreeOid m
treeEntry :: Repository m => Tree m -> TreeFilePath -> m (Maybe (TreeEntry m))
listTreeEntries :: Repository m => Tree m -> m [(TreeFilePath, TreeEntry m)]
diffContentsWithTree :: Repository m => Source m (Either TreeFilePath ByteString) -> Tree m -> Producer m ByteString
hashContents :: Repository m => BlobContents m -> m (BlobOid m)
createBlob :: Repository m => BlobContents m -> m (BlobOid m)
createCommit :: Repository m => [CommitOid m] -> TreeOid m -> Signature -> Signature -> CommitMessage -> Maybe RefName -> m (Commit m)
createTag :: Repository m => CommitOid m -> Signature -> CommitMessage -> Text -> m (Tag m)
data RepositoryOptions
RepositoryOptions :: !FilePath -> !Bool -> !Bool -> RepositoryOptions
repoPath :: RepositoryOptions -> !FilePath
repoIsBare :: RepositoryOptions -> !Bool
repoAutoCreate :: RepositoryOptions -> !Bool
data RepositoryFactory t m c
RepositoryFactory :: (RepositoryOptions -> m c) -> (forall a. c -> t a -> m a) -> (c -> m ()) -> t c -> !RepositoryOptions -> m () -> m () -> RepositoryFactory t m c
openRepository :: RepositoryFactory t m c -> RepositoryOptions -> m c
runRepository :: RepositoryFactory t m c -> forall a. c -> t a -> m a
closeRepository :: RepositoryFactory t m c -> c -> m ()
getRepository :: RepositoryFactory t m c -> t c
defaultOptions :: RepositoryFactory t m c -> !RepositoryOptions
startupBackend :: RepositoryFactory t m c -> m ()
shutdownBackend :: RepositoryFactory t m c -> m ()
class (Eq o, Ord o, Show o) => IsOid o where renderOid = renderObjOid . Tagged renderObjOid = renderOid . untag
renderOid :: IsOid o => o -> Text
renderObjOid :: IsOid o => Tagged a o -> Text
type BlobOid m = Tagged (Blob m) (Oid m)
type TreeOid m = Tagged (Tree m) (Oid m)
type CommitOid m = Tagged (Commit m) (Oid m)
type TagOid m = Tagged (Tag m) (Oid m)
data ObjectOid m
BlobObjOid :: !(BlobOid m) -> ObjectOid m
TreeObjOid :: !(TreeOid m) -> ObjectOid m
CommitObjOid :: !(CommitOid m) -> ObjectOid m
TagObjOid :: !(TagOid m) -> ObjectOid m
parseObjOid :: Repository m => forall o. Text -> m (Tagged o (Oid m))
copyOid :: (Repository m, Repository n) => Oid m -> n (Oid n)
newtype SHA
SHA :: ByteString -> SHA
getSHA :: SHA -> ByteString
shaToText :: SHA -> Text
textToSha :: Monad m => Text -> m SHA
data Blob m
Blob :: !(BlobOid m) -> !(BlobContents m) -> Blob m
blobOid :: Blob m -> !(BlobOid m)
blobContents :: Blob m -> !(BlobContents m)
type ByteSource m = Producer m ByteString
data BlobContents m
BlobString :: !ByteString -> BlobContents m
BlobStream :: !(ByteSource m) -> BlobContents m
BlobSizedStream :: !(ByteSource m) -> !Int -> BlobContents m
data BlobKind
PlainBlob :: BlobKind
ExecutableBlob :: BlobKind
SymlinkBlob :: BlobKind
UnknownBlob :: BlobKind
data TreeEntry m
BlobEntry :: !(BlobOid m) -> !BlobKind -> TreeEntry m
blobEntryOid :: TreeEntry m -> !(BlobOid m)
blobEntryKind :: TreeEntry m -> !BlobKind
TreeEntry :: !(TreeOid m) -> TreeEntry m
treeEntryOid :: TreeEntry m -> !(TreeOid m)
CommitEntry :: !(CommitOid m) -> TreeEntry m
commitEntryOid :: TreeEntry m -> !(CommitOid m)
treeEntryToOid :: Repository m => TreeEntry m -> Oid m
data TreeBuilder m
TreeBuilder :: Maybe (TreeOid m) -> HashMap TreeFilePath (TreeBuilder m) -> (Maybe (Tree m) -> m (TreeBuilder m)) -> (TreeBuilder m -> m (ModifiedBuilder m, TreeOid m)) -> (TreeFilePath -> m (Maybe (TreeEntry m))) -> m Int -> (TreeBuilder m -> TreeFilePath -> TreeEntry m -> m (ModifiedBuilder m)) -> (TreeBuilder m -> TreeFilePath -> m (ModifiedBuilder m)) -> TreeBuilder m
mtbBaseTreeOid :: TreeBuilder m -> Maybe (TreeOid m)
mtbPendingUpdates :: TreeBuilder m -> HashMap TreeFilePath (TreeBuilder m)
mtbNewBuilder :: TreeBuilder m -> Maybe (Tree m) -> m (TreeBuilder m)
mtbWriteContents :: TreeBuilder m -> TreeBuilder m -> m (ModifiedBuilder m, TreeOid m)
mtbLookupEntry :: TreeBuilder m -> TreeFilePath -> m (Maybe (TreeEntry m))
mtbEntryCount :: TreeBuilder m -> m Int
mtbPutEntry :: TreeBuilder m -> TreeBuilder m -> TreeFilePath -> TreeEntry m -> m (ModifiedBuilder m)
mtbDropEntry :: TreeBuilder m -> TreeBuilder m -> TreeFilePath -> m (ModifiedBuilder m)
data ModifiedBuilder m
ModifiedBuilder :: (TreeBuilder m) -> ModifiedBuilder m
BuilderUnchanged :: (TreeBuilder m) -> ModifiedBuilder m
fromBuilderMod :: ModifiedBuilder m -> TreeBuilder m
data Commit m
Commit :: !(CommitOid m) -> ![CommitOid m] -> !(TreeOid m) -> !Signature -> !Signature -> !CommitMessage -> !Text -> Commit m
commitOid :: Commit m -> !(CommitOid m)
commitParents :: Commit m -> ![CommitOid m]
commitTree :: Commit m -> !(TreeOid m)
commitAuthor :: Commit m -> !Signature
commitCommitter :: Commit m -> !Signature
commitLog :: Commit m -> !CommitMessage
commitEncoding :: Commit m -> !Text
lookupCommitParents :: Repository m => Commit m -> m [Commit m]
data Signature
Signature :: !CommitAuthor -> !CommitEmail -> !ZonedTime -> Signature
signatureName :: Signature -> !CommitAuthor
signatureEmail :: Signature -> !CommitEmail
signatureWhen :: Signature -> !ZonedTime
data Tag m
Tag :: !(TagOid m) -> !(CommitOid m) -> Tag m
tagOid :: Tag m -> !(TagOid m)
tagCommit :: Tag m -> !(CommitOid m)
data Object m
BlobObj :: !(Blob m) -> Object m
TreeObj :: !(Tree m) -> Object m
CommitObj :: !(Commit m) -> Object m
TagObj :: !(Tag m) -> Object m
objectOid :: Repository m => Object m -> Oid m
loadObject :: Repository m => ObjectOid m -> m (Object m)
objectToObjOid :: Repository m => Object m -> ObjectOid m
untagObjOid :: Repository m => ObjectOid m -> Oid m
data RefTarget m
RefObj :: !(Oid m) -> RefTarget m
RefSymbolic :: !RefName -> RefTarget m
commitRefTarget :: Commit m -> RefTarget m
data ModificationKind
Unchanged :: ModificationKind
Modified :: ModificationKind
Added :: ModificationKind
Deleted :: ModificationKind
TypeChanged :: ModificationKind
data MergeStatus
NoConflict :: MergeStatus
BothModified :: MergeStatus
LeftModifiedRightDeleted :: MergeStatus
LeftDeletedRightModified :: MergeStatus
BothAdded :: MergeStatus
LeftModifiedRightTypeChanged :: MergeStatus
LeftTypeChangedRightModified :: MergeStatus
LeftDeletedRightTypeChanged :: MergeStatus
LeftTypeChangedRightDeleted :: MergeStatus
BothTypeChanged :: MergeStatus
mergeStatus :: ModificationKind -> ModificationKind -> MergeStatus
data MergeResult m
MergeSuccess :: CommitOid m -> MergeResult m
mergeCommit :: MergeResult m -> CommitOid m
MergeConflicted :: CommitOid m -> CommitOid m -> CommitOid m -> Map TreeFilePath (ModificationKind, ModificationKind) -> MergeResult m
mergeCommit :: MergeResult m -> CommitOid m
mergeHeadLeft :: MergeResult m -> CommitOid m
mergeHeadRight :: MergeResult m -> CommitOid m
mergeConflicts :: MergeResult m -> Map TreeFilePath (ModificationKind, ModificationKind)
copyMergeResult :: (Repository m, MonadGit m, Repository n, MonadGit n) => MergeResult m -> n (MergeResult n)

-- | There is a separate <a>GitException</a> for each possible failure when
--   interacting with the Git repository.
data GitException
BackendError :: Text -> GitException
GitError :: Text -> GitException
RepositoryNotExist :: GitException
RepositoryInvalid :: GitException
RepositoryCannotAccess :: Text -> GitException
BlobCreateFailed :: Text -> GitException
BlobEmptyCreateFailed :: GitException
BlobEncodingUnknown :: Text -> GitException
BlobLookupFailed :: GitException
DiffBlobFailed :: Text -> GitException
DiffPrintToPatchFailed :: Text -> GitException
DiffTreeToIndexFailed :: Text -> GitException
IndexAddFailed :: TreeFilePath -> Text -> GitException
IndexCreateFailed :: Text -> GitException
PushNotFastForward :: Text -> GitException
TranslationException :: Text -> GitException
TreeCreateFailed :: Text -> GitException
TreeBuilderCreateFailed :: GitException
TreeBuilderInsertFailed :: TreeFilePath -> GitException
TreeBuilderRemoveFailed :: TreeFilePath -> GitException
TreeBuilderWriteFailed :: Text -> GitException
TreeLookupFailed :: GitException
TreeCannotTraverseBlob :: GitException
TreeCannotTraverseCommit :: GitException
TreeEntryLookupFailed :: TreeFilePath -> GitException
TreeUpdateFailed :: GitException
TreeWalkFailed :: GitException
TreeEmptyCreateFailed :: GitException
CommitCreateFailed :: GitException
CommitLookupFailed :: Text -> GitException
ReferenceCreateFailed :: RefName -> GitException
ReferenceDeleteFailed :: RefName -> GitException
RefCannotCreateFromPartialOid :: GitException
ReferenceListingFailed :: GitException
ReferenceLookupFailed :: RefName -> GitException
ObjectLookupFailed :: Text -> Int -> GitException
ObjectRefRequiresFullOid :: GitException
OidCopyFailed :: GitException
OidParseFailed :: Text -> GitException
QuotaHardLimitExceeded :: Int -> Int -> GitException
instance Typeable GitException
instance Show RepositoryFacts
instance Eq SHA
instance Ord SHA
instance Read SHA
instance Show BlobKind
instance Eq BlobKind
instance Enum BlobKind
instance Show Signature
instance Eq ModificationKind
instance Ord ModificationKind
instance Enum ModificationKind
instance Show ModificationKind
instance Read ModificationKind
instance Eq MergeStatus
instance Ord MergeStatus
instance Enum MergeStatus
instance Show MergeStatus
instance Read MergeStatus
instance Eq GitException
instance Show GitException
instance Exception GitException
instance Repository m => Show (MergeResult m)
instance Repository m => Show (RefTarget m)
instance Default Signature
instance Monoid (ModifiedBuilder m)
instance Repository m => Show (TreeEntry m)
instance Eq (BlobContents m)
instance Hashable SHA
instance Binary SHA
instance Show SHA
instance IsOid SHA
instance Default RepositoryOptions

module Git.Tree.Builder
data TreeT m a
data TreeBuilder m
TreeBuilder :: Maybe (TreeOid m) -> HashMap TreeFilePath (TreeBuilder m) -> (Maybe (Tree m) -> m (TreeBuilder m)) -> (TreeBuilder m -> m (ModifiedBuilder m, TreeOid m)) -> (TreeFilePath -> m (Maybe (TreeEntry m))) -> m Int -> (TreeBuilder m -> TreeFilePath -> TreeEntry m -> m (ModifiedBuilder m)) -> (TreeBuilder m -> TreeFilePath -> m (ModifiedBuilder m)) -> TreeBuilder m
mtbBaseTreeOid :: TreeBuilder m -> Maybe (TreeOid m)
mtbPendingUpdates :: TreeBuilder m -> HashMap TreeFilePath (TreeBuilder m)
mtbNewBuilder :: TreeBuilder m -> Maybe (Tree m) -> m (TreeBuilder m)
mtbWriteContents :: TreeBuilder m -> TreeBuilder m -> m (ModifiedBuilder m, TreeOid m)
mtbLookupEntry :: TreeBuilder m -> TreeFilePath -> m (Maybe (TreeEntry m))
mtbEntryCount :: TreeBuilder m -> m Int
mtbPutEntry :: TreeBuilder m -> TreeBuilder m -> TreeFilePath -> TreeEntry m -> m (ModifiedBuilder m)
mtbDropEntry :: TreeBuilder m -> TreeBuilder m -> TreeFilePath -> m (ModifiedBuilder m)
data ModifiedBuilder m
ModifiedBuilder :: (TreeBuilder m) -> ModifiedBuilder m
BuilderUnchanged :: (TreeBuilder m) -> ModifiedBuilder m
createTree :: Repository m => TreeT m a -> m (TreeOid m)
withNewTree :: Repository m => TreeT m a -> m (a, TreeOid m)
mutateTree :: Repository m => Tree m -> TreeT m a -> m (TreeOid m)
mutateTreeOid :: Repository m => TreeOid m -> TreeT m a -> m (TreeOid m)
currentTree :: Repository m => TreeT m (Tree m)
currentTreeOid :: Repository m => TreeT m (TreeOid m)
withTree :: Repository m => Tree m -> TreeT m a -> m (a, TreeOid m)
withTreeOid :: Repository m => TreeOid m -> TreeT m a -> m (a, TreeOid m)
dropEntry :: Repository m => TreeFilePath -> TreeT m ()
getEntry :: Repository m => TreeFilePath -> TreeT m (Maybe (TreeEntry m))
putBlob :: Repository m => TreeFilePath -> BlobOid m -> TreeT m ()
putBlob' :: Repository m => TreeFilePath -> BlobOid m -> BlobKind -> TreeT m ()
putCommit :: Repository m => TreeFilePath -> CommitOid m -> TreeT m ()
putEntry :: Repository m => TreeFilePath -> TreeEntry m -> TreeT m ()
putTree :: Repository m => TreeFilePath -> TreeOid m -> TreeT m ()
treeEntry :: Repository m => Tree m -> TreeFilePath -> m (Maybe (TreeEntry m))
data ModifyTreeResult m
TreeEntryNotFound :: ModifyTreeResult m
TreeEntryDeleted :: ModifyTreeResult m
TreeEntryPersistent :: (TreeEntry m) -> ModifyTreeResult m
TreeEntryMutated :: (TreeEntry m) -> ModifyTreeResult m
fromModifyTreeResult :: ModifyTreeResult m -> Maybe (TreeEntry m)
toModifyTreeResult :: (TreeEntry m -> ModifyTreeResult m) -> Maybe (TreeEntry m) -> ModifyTreeResult m
emptyTreeId :: Text
instance Eq BuilderAction
instance Show BuilderAction
instance MonadIO m => MonadIO (TreeT m)
instance MonadTrans TreeT
instance MonadFix m => MonadFix (TreeT m)
instance MonadPlus m => MonadPlus (TreeT m)
instance (Functor m, MonadPlus m) => Alternative (TreeT m)
instance (Functor m, Monad m) => Applicative (TreeT m)
instance Monad m => Monad (TreeT m)
instance Functor m => Functor (TreeT m)

module Git.Repository
withNewRepository :: (Repository t, MonadGit t, MonadBaseControl IO m, MonadIO m) => RepositoryFactory t m c -> FilePath -> t a -> m a
withNewRepository' :: (Repository t, MonadGit t, MonadBaseControl IO m, MonadIO m) => RepositoryFactory t m c -> FilePath -> t a -> m a
withBackendDo :: (MonadIO m, MonadBaseControl IO m) => RepositoryFactory t m a -> m b -> m b
withRepository' :: (Repository t, MonadBaseControl IO m, MonadIO m) => RepositoryFactory t m c -> RepositoryOptions -> t a -> m a
withRepository :: (Repository t, MonadBaseControl IO m, MonadIO m) => RepositoryFactory t m c -> FilePath -> t a -> m a

module Git.Reference
resolveReference :: Repository m => RefName -> m (Maybe (Oid m))
referenceToOid :: Repository m => RefTarget m -> m (Maybe (Oid m))

module Git.Object
listObjects :: Repository m => Maybe (CommitOid m) -> CommitOid m -> Bool -> m [ObjectOid m]
traverseObjects :: Repository m => (ObjectOid m -> m a) -> CommitOid m -> m [a]
traverseObjects_ :: Repository m => (ObjectOid m -> m ()) -> CommitOid m -> m ()

-- | Given a list of objects (commit and top-level trees) return by
--   <a>listObjects</a>, expand it to include all subtrees and blobs as
--   well. Ordering is preserved.
expandTreeObjects :: Repository m => Conduit (ObjectOid m) m (ObjectOid m)
listAllObjects :: Repository m => Maybe (CommitOid m) -> CommitOid m -> m [ObjectOid m]

module Git.Blob
createBlobUtf8 :: Repository m => Text -> m (BlobOid m)
catBlob :: Repository m => BlobOid m -> m ByteString
catBlobUtf8 :: Repository m => BlobOid m -> m Text
blobContentsToByteString :: Repository m => BlobContents m -> m ByteString
blobToByteString :: Repository m => Blob m -> m ByteString
treeBlobEntries :: Repository m => Tree m -> m [(TreeFilePath, BlobOid m, BlobKind)]
copyBlob :: (Repository m, Repository (t m), MonadTrans t) => BlobOid m -> HashSet Text -> t m (BlobOid (t m), HashSet Text)

module Git.Tree
copyTreeEntry :: (Repository m, Repository (t m), MonadTrans t) => TreeEntry m -> HashSet Text -> t m (TreeEntry (t m), HashSet Text)
copyTree :: (Repository m, Repository (t m), MonadTrans t) => TreeOid m -> HashSet Text -> t m (TreeOid (t m), HashSet Text)

module Git.Commit
commitTreeEntry :: Repository m => Commit m -> TreeFilePath -> m (Maybe (TreeEntry m))
copyCommitOid :: (Repository m, Repository n) => CommitOid m -> n (CommitOid n)
copyCommit :: (Repository m, Repository (t m), MonadTrans t) => CommitOid m -> Maybe RefName -> HashSet Text -> t m (CommitOid (t m), HashSet Text)
listCommits :: Repository m => Maybe (CommitOid m) -> CommitOid m -> m [CommitOid m]
traverseCommits :: Repository m => (CommitOid m -> m a) -> CommitOid m -> m [a]
traverseCommits_ :: Repository m => (CommitOid m -> m ()) -> CommitOid m -> m ()

module Git.Commit.Push

-- | Fast-forward push a reference between repositories using a recursive
--   copy. This can be extremely slow, but always works no matter which two
--   backends are being used. It should be considered a matter of last
--   resort, or for objects sets that are known to be small.
pushCommit :: (Repository m, Repository (t m), MonadTrans t) => CommitOid m -> Text -> t m (CommitOid (t m))


-- | Interface for working with Git repositories.
module Git

module Git.Tree.Builder.Pure
type EntryHashMap m = HashMap TreeFilePath (TreeEntry m)

-- | Create a new, empty tree.
--   
--   Since empty trees cannot exist in Git, attempting to write out an
--   empty tree is a no-op.
newPureTreeBuilder :: Repository m => (Tree m -> m (EntryHashMap m)) -> (EntryHashMap m -> m (TreeOid m)) -> Maybe (Tree m) -> m (TreeBuilder m)