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

       Stanislav Sinyagin <ssinyagin@k-open.com>

       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.

perl v5.26.2                                       2018-07-21                              Git::ObjectStore(3pm)

       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.

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.

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

         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);
         }

       version 0.007