Git::ObjectStore(3pm)

💖 Git::ObjectStore 💖

okay bestie, so this page is Git::ObjectStore(3pm) from the User Contributed Perl Documentation — and it's literally the cutest little abstraction layer, you're gonna be obsessed.

---

✨ NAME ✨

Git::ObjectStore — an abstraction layer for Git::Raw and libgit2. periodt.

---

🌸 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 🎀

So basically, this module gives you an abstraction layer on top of Git::Raw (which is a Perl wrapper for libgit2), and its whole thing is letting you use a bare Git repository as an object store. 💅

The objects get written into a mempack first, and then flushed to disk. Which means you can create thousands of objects without polluting your filesystem and exhausting its inode pool. it's giving efficiency, it's giving main character energy, no cap. 🔥

---

👑 METHODS 👑

💫 new(%args)

Creates a new object. And here's the tea: if repodir is empty or does not exist, the method initializes a new bare Git repository — but only in writer mode. Also, if multiple processes might call this method at the same time, it's up to you to provide locking and prevent the race condition. that's on you bestie, the module is not doing it for you. 😭

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. cute, right?

💫 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 exists in the branch. In reader mode, it also returns true if path is a directory name. iykyk.

💫 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. 💀 (in a good way)

💫 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. go fast, bestie. 🔥

💫 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. iconic default tbh. ✨

💫 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. don't forget this step, bestie, i'm begging 😭

💫 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. sneaky but correct. 💅

💫 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 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.

---

and that's the whole page, bestie 💖 this gem was served up by perl v5.26.2 on 2018-07-21 under the Git::ObjectStore(3pm) name — now go write some objects, you absolute icon 👑💅