/ 
Git-Native-0.004
/ Git::Native::Repository

NAME

Git::Native::Repository - A libgit2 repository handle

VERSION

version 0.004

SYNOPSIS

my $repo = Git::Native->open('/path/to/.git');
my $main = $repo->reference('refs/heads/main');
say $main->target;

my $blob_oid = $repo->blob_create_frombuffer("hi\n");
my $tb       = $repo->tree_builder;
$tb->insert(name => 'hi.txt', oid => $blob_oid, mode => 0100644);
my $tree_oid = $tb->write;
my $commit_oid = $repo->commit_create(
  update_ref => 'HEAD',
  tree       => $tree_oid,
  parents    => [$main->target],
  message    => 'add greeting',
);

DESCRIPTION

The main entry point for working with a Git repository through Git::Native. Wraps git_repository*; freed automatically.

reference_create

my $ref = $repo->reference_create(
  'refs/heads/main', $new_oid,
  expected_old => $old_oid,
);

Create or update a direct reference. force and message retain their usual meaning for unconditional calls. Supplying expected_old makes the update compare-and-swap: the write succeeds only while the reference points to that OID, otherwise it throws a Git::Native::Error for which is_not_matched is true. An explicit expected_old => undef requires the reference to be absent and creates it atomically.

This path requires Git::Libgit2 to bind git_reference_create_matching. If it does not, the method throws an actionable function-not-bound error instead of attempting an unavailable FFI call.

reference_set_target

my $ref = $repo->reference_set_target(
  'refs/heads/main', $new_oid,
  expected_old => $old_oid,
);

Atomically update an existing direct reference by name. expected_old is required. A stale expected OID throws a Git::Native::Error for which is_not_matched is true and leaves the reference unchanged.

libgit2 does not provide a git_reference_set_target_matching function. This method looks up the reference, checks the caller's expected OID, then uses git_reference_set_target, which atomically guards its write against the OID in that looked-up reference.

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/p5-git-native/issues.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <getty@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/.

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