NAME

Git::Database::Tutorial - Learn how to use Git::Database

VERSION

version 0.004

SYNOPSIS

    use Git::Database;

    # do cool stuff with Git, using the following advice
    # and the Perl Git wrapper of your choice

GLOSSARY

repository

The local Git repository, as managed by git.

backend

A class doing the Git::Database::Role::Backend role. The Git::Database module acts as a frontend that returns a backend object.

It manages all interactions with the Git repository, via its store. A backend instance is always connected to a store instance.

The backend interface is split across several roles, each requiring one or more access methods to be defined. The roles are: Git::Database::Role::Backend (this is the minimum required role that a class must do to be considered a backend), Git::Database::Role::ObjectReader, Git::Database::Role::ObjectWriter, Git::Database::Role::RefReader and Git::Database::Role::RefWriter.

Git::Database::Backend::None is a special backend class that is not connected to a store. The only supported method is hash_object.

store

The Perl Git wrapper that reads and write the data from and to the repository.

A store instance is always connected to an actual Git repository.

The backend class is named after the store class. For example, the backend class for Git::Repository stores is named Git::Database::Backend::Git::Repository.

The currently supported stores are: Git::Repository, Git::Sub, Git::PurePerl, Cogit, and Git. Several branches exist in the development repository to add support for other Git wrappers. Patches welcome!

object

An object from the Git object database. Represented in Perl by the Git::Database::Object::Blob, Git::Database::Object::Tree, Git::Database::Object::Commit and Git::Database::Object::Tag classes.

ref

A reference (tag or branch) in the Git repository.

HOW TO

Obtain a Git::Database object from an existing repository

The Git::Database module is really a simple factory class that returns "backend" objects. The actual backend class depends on the Git wrapper module used to access the Git repository.

The generic way is:

    # $r is an instance of some Perl Git wrapper
    my $db = Git::Database->new( store => $r );

For example, if $r is a Git::Repository object, $db is going to be a Git::Database::Backend::Git::Repository object.

Example:

    # use Git::Repository with a repository in the current working directory
    my $db = Git::Database->new( store => Git::Repository->new );

    $db->isa('Git::Database::Backend::Git::Repository');    # true

Git::Sub is a special backend, as it's the only one that does not provide an object-oriented interface. When given a "store" that does not the Git::Database::Role::Backend role, Git::Database assumes it's a directory name, and creates a Git::Database::Backend::Git::Sub object to handle it.

For the moment, there is no way to perform an "automatic selection" of the backend based on what's available.

Create a new repository using Git::Database

This is outside of the realm of Git::Database, since it must be handed an existing "store" object.

The Git::Repository::Tutorial documentation has detailed examples of how to create or clone a new repository.

Other Git wrappers may also be able to create new repositories.

The resulting object can then be passed to Git::Database->new as the store attribute.

Create a Git object

There are two ways to create a Git object (doing the Git::Database::Role::Object role), with subtle differences between them.

using the class directly

    my $blob = Git::Database::Object::Blob->new( content => "Hello, world!" );

    $blob->isa('Git::Database::Object::Blob');    # true
    $blob->has_backend;                           # false
    $blob->digest;    # use hash_object() from Git::Database::Role::Backend

using the backend

    my $blob = $backend->create_object( content => "Hello, world!" );

    $blob->isa('Git::Database::Object::Blob');    # true
    $blob->has_backend;                           # true
    $blob->digest;    # use hash_object from $backend (might be faster)

AUTHOR

Philippe Bruhat (BooK) <book@cpan.org>.

COPYRIGHT

Copyright 2016 Philippe Bruhat (BooK), all rights reserved.

LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Git::Database

perl -MCPAN -e shell
install Git::Database