/ 
Git-Database-0.012
River stage zero No dependents
/ Git::Database::Tutorial

NAME

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

VERSION

version 0.012

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 (by order of appearance): Git::Repository, Git::Sub, Git::PurePerl, Cogit, Git, Git::Wrapper, and Git::Raw::Repository. If you know of other Git wrappers, please let me know or submit patches. Thanks!

The following one-liner will list which stores are currently installed:

perl -MGit::Database -E 'say for Git::Database->available_stores'
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::Backend::None
$blob->has_backend;                           # true
$blob->backend->isa("Git::Database::Backend::None");
using the backend
my $blob = $backend->create_object( kind => 'blob',  content => "Hello, world!" );
$blob->isa("Git::Database::Object::Blob");    # true
$blob->has_backend;                           # true
$blob->digest;    # use hash_object() from $backend (might be faster)
$blob->backend->isa( ref $backend );

When no backend is provided, a default Git::Database::Backend::None is created as needed. Its hash_object method is the default implementation provided by Git::Database::Role::Backend.

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.