Provided by: libgit-objectstore-perl_0.007-2build1_all 
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.
perl v5.40.1 2025-11-24 Git::ObjectStore(3pm)