NAME
Git::ObjectStore - abstraction layer for Git::Raw and libgit2
VERSION
version 0.003
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 initializes a new bare Git repository. If multiple processes may call this method simultaneously, it is up to you to provide locking, so that the objects are created one at a time.
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.
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.
recursive_read($path, $callback)
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.
read_updates($old_commit_id, $callback_updated, $callback_deleted)
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.
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.