NAME

       Git::ObjectStore - abstraction layer for Git::Raw and libgit2

VERSION

       version 0.007

SYNOPSIS

         use Git::ObjectStore;

         ### Writer example ###
         my $store = new Git::ObjectStore('repodir' => $dir,
                                          'branchname' => $bname,
                                          'writer' => 1);

         # write the documents into the store
         my $is_changed = $store->write_and_check('docs/001a', \$doc1text);
         $store->write_file('docs/001b', \$doc2text);

         # documents can be read from the writer object
         my $doc = $store->read_file('docs/001c');

         # check if a document exists and delete it
         if( $store->file_exists('docs/001d') ) {
             $store->delete_file('docs/001d');
         }

         # once the changes are finished, create commit and write it to disk
         $store->create_commit_and_packfile();

         ### Reader example ###
         my $store = new Git::ObjectStore('repodir' => $dir,
                                          'branchname' => $bname);

         # checking existance or reading individual files
         $store->file_exists('docs/001d') and print "file exists\n";
         my $doc = $store->read_file('docs/001c');

         # read all files in a directory and its subdirectories
         my $cb_read = sub {
             my ($path, $data) = @_;
             print("$path: $data\n");
         };
         $store->recursive_read('docs', $cb_read);

         # Check if there are changes and read the updates
         my $cb_updated = sub {
             my ($path, $data) = @_;
             print("Updated $path: $data\n");
         };
         my $cb_deleted = sub {
             my ($path) = @_;
             print("Deleted $path\n");
         };
         if( $store->current_commit_id() ne $old_commit_id ) {
             $store->read_updates($old_commit_id, $cb_updated, $cb_deleted);
         }

DESCRIPTION

       This module provides an abstraction layer on top of Git::Raw, a Perl wrapper for libgit2,
       in order to use a bare Git repository as an object store. The objects are written into a
       mempack, and then flushed to disk, so thousands of objects can be created without
       polluting your filesystem and exhausting its inode pool.

METHODS

   new(%args)
       Creates a new object. If repodir is empty or does not exist, the method (in writer mode
       only) initializes a new bare Git repository. If multiple processes may call this method
       simultaneously, it is up to you to provide locking and prevent the race condition.

       Mandatory arguments:

       •   "repodir": the directory path where the bare Git repository is located.

       •   "branchname": the branch name in the repository. Multiple Git::ObjectStore objects can
           co-exist at the same time in multiple or the same process, but the branch names in
           writer objects need to be unique.

       Optional arguments:

       •   "writer": set to true if this object needs to write new files into the repository.
           Writing is always done at the top of the branch.

       •   "goto": commit identifier where the read operations will be performed. This argument
           cannot be combined with writer mode. By default, reading is performed from the top of
           the branch.

       •   "author_name", "author_email": name and email strings used for commits.

   created_init_commit()
       If a "Git::ObjectStore" object is created in writer mode and the branch did not exist, the
       "new()" method creates an empty initial commit in this branch. This method returns the
       initial commit ID, or undef if the branch already existed.

   repo()
       This method returns a Git::Raw::Repository object associated with this store object.

   read_file($path)
       This method reads a file from a given path within the branch. It returns undef if the file
       is not found. In writer mode, the file is checked first in the in-memory mempack. The
       returned value is the file content as a scalar.

   file_exists($path)
       This method returns true if the given file extsis in the branch. In reader mode, it also
       returns true if path is a directory name.

   current_commit_id()
       Returns the current commit identifier. This can be useful for detecting if there are any
       changes in the branch and retrieve the difference.

   write_and_check($path, $data)
       This method writes the data scalar to the repository under specified file name. It returns
       true if the data differs from the previous version or a new file is created. It returns
       false if the new data is identical to what has been written before. The data can be a
       scalar or a reference to scalar.

   write_file($path, $data)
       This method is similar to "write_and_check", but it does not compare the content
       revisions. It is useful for massive write operations where speed is important.

   delete_file($path)
       This method deletes a file from the branch. It throws an error if the file does not exist
       in the branch.

   create_commit([$msg])
       This method checks if any new content is written, and creates a Git commit if there is a
       change. The return value is true if a new commit has been created, or false otherwise. An
       optional argument can specify the commit message. If a message is not specified, current
       localtime is used instead.

   write_packfile()
       This method writes the contents of mempack onto the disk. This method must be called after
       one or several calls of "create_commit()", so that the changes are written to persistent
       storage.

   create_commit_and_packfile([$msg])
       This method combines "create_commit()" and "write_packfile". The packfile is only written
       if there is a change in the content. The method returns true if any changes were detected.
       If it's a new branch and it only contains the empty initial commit, a packfile is written
       and the method returns false.

   recursive_read($path, $callback, $no_content)
       This method is only supported in reader mode. It reads the directories recursively and
       calls the callback for every file it finds. The callback arguments are the file name and
       scalar content. If called with string as path, all files in the branch are traversed. If
       the third argument is a true value, the method does not read the object contents, and the
       callback is only called with one argument.

   read_updates($old_commit_id, $callback_updated, $callback_deleted, $no_content)
       This method is only supported in reader mode. It compares the current commit with the old
       commit, and executes the first callback for all added or updated files, and the second
       callback for all deleted files. The first callback gets the file name and scalar content
       as arguments, and the second callback gets only the file name. If the fourth argument is
       true, the update callback is called only with rhe file name.

AUTHOR

       Stanislav Sinyagin <ssinyagin@k-open.com>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2017 by Stanislav Sinyagin.

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