NAME

GitStore - Git as versioned data store in Perl

VERSION

version 0.17

SYNOPSIS

    use GitStore;

    my $gs = GitStore->new('/path/to/repo');
    $gs->set( 'users/obj.txt', $obj );
    $gs->set( ['config', 'wiki.txt'], { hash_ref => 1 } );
    $gs->commit();
    $gs->set( 'yyy/xxx.log', 'Log me' );
    $gs->discard();
    
    # later or in another pl
    my $val = $gs->get( 'user/obj.txt' ); # $val is the same as $obj
    my $val = $gs->get( 'config/wiki.txt' ); # $val is { hashref => 1 } );
    my $val = $gs->get( ['yyy', 'xxx.log' ] ); # $val is undef since discard

DESCRIPTION

It is inspired by the Python and Ruby binding. check SEE ALSO

CLASS FUNCTIONS

create( $directory )

Creates the directory, initialize it as a git repository, and returns its associated GitStore object.

    my $gs = GitStore->create( '/tmp/mystore' );

METHODS

new

    GitStore->new('/path/to/repo');
    GitStore->new( repo => '/path/to/repo', branch => 'mybranch' );
    GitStore->new( repo => '/path/to/repo', author => 'Someone Unknown <unknown\@what.com>' );

repo

your git directory or work directory (GitStore will assume it's a work directory if it doesn't end with .git).

branch

your branch name, default is 'master'

author

It is used in the commit info

serializer

Can be used to define a serializing function that will be used if the value to save is a reference. When invoked, the function will be passed a reference to the store object, the path under which the value will be saved, and the value itself. For example, one could do different serialization via:

    my $store = GitStore->new(
        repo => '/path/to/repo',
        serializer => sub {
            my( $store, $path, $value ) = @_;

            if ( $path =~ m#^json# ) {
                return encode_json($value);
            }
            else {
                # defaults to YAML
                return YAML::Dump($value);
            }
        },
    );

The default serializer uses "nfreeze" in Storable.

deserializer

Called when a value is picked from the store to be (potentially) deserialized. Just like the serializer function, it is passed three arguments: the store object, the path of the value to deserialize and the value itself. To revisit the example for serializer, the full serializer/deserializer dance would be:

    my $store = GitStore->new(
        repo => '/path/to/repo',
        serializer => sub {
            my( $store, $path, $value ) = @_;

            return $path =~ m#^json# 
                                ? encode_json($value)
                                : YAML::Dump($value)
                                ;
        },
        deserializer => sub {
            my( $store, $path, $value ) = @_;
            
            return $path =~ #^json#
                                ?decode_json($value)
                                : YAML::Load($value)
                                ;
        },
    );

The default deserializer will try to deserialize the value retrieved from the store via "thaw" in Storable and, if this fails, return the value verbatim.

autocommit

If set to true, any call to set() or delete() will automatically call an implicit commit(). Defaults to false.

set($path, $val)

    $gs->set( 'yyy/xxx.log', 'Log me' );
    $gs->set( ['config', 'wiki.txt'], { hash_ref => 1 } );
    $gs->set( 'users/obj.txt', $obj );

Store $val as a $path file in Git

$path can be String or ArrayRef. Any leading slashes ('/') in the path will be stripped, as to make it a valid Git path. The same grooming is done for the get() and delete() methods.

$val can be String or Ref[HashRef|ArrayRef|Ref[Ref]] or blessed Object

get($path)

    $gs->get( 'user/obj.txt' );
    $gs->get( ['yyy', 'xxx.log' ] );

Get $val from the $path file

$path can be String or ArrayRef

get_revision( $path )

Like get(), but returns the GitStore::Revision object corresponding to the latest Git revision on the monitored branch for which $path changed.

delete($path)

remove($path)

remove $path from Git store

commit

    $gs->commit();
    $gs->commit('Your Comments Here');

commit the set changes into Git

discard

    $gs->discard();

discard the set changes

exist($path)

Returns true if an object exists at the given path.

history($path)

Returns a list of GitStore::Revision objects representing the changes brought to the $path. The changes are returned in ascending commit order.

list($regex)

    @entries = $gs->list( qr/\.txt$/ );

Returns a list of all entries in the repository, possibly filtered by the optional $regex.

FAQ

why the files are not there?

run

    git checkout

any example?

    # if you just need a local repo, that's all you need.
    mkdir sandbox
    cd sandbox
    git init
    # use GitStore->new('/path/to/this/sandbox')
    # set something
    git checkout
    
    # follows are for remote git url
    git remote add origin git@github.com:fayland/sandbox2.git
    git push origin master
    # do more GitStore->new('/path/to/this/sandbox') later
    git checkout
    git pull origin master
    git push

KNOWN BUGS

If all files are deleted from the repository, a 'dummy' file will be created to keep Git happy.

SEE ALSO

Article

http://www.newartisans.com/2008/05/using-git-as-a-versioned-data-store-in-python.html

Python binding

http://github.com/jwiegley/git-issues/tree/master

Ruby binding

http://github.com/georgi/git_store/tree/master

Git URL

http://github.com/fayland/perl-git-store/tree/master

AUTHORS

• Fayland Lam <fayland@gmail.com>

• Yanick Champoux <yanick@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2015 by Fayland Lam <fayland@gmail.com>.

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

cpanm GitStore

perl -MCPAN -e shell
install GitStore