view release on metacpan or  search on metacpan

lib/Git/Libgit2.pm  view on Meta::CPAN

  use Git::Libgit2 qw( init_lib version check_rc );

  init_lib();
  printf "libgit2 %s\n", version();

  # Direct FFI calls live in Git::Libgit2::FFI
  use Git::Libgit2::FFI;
  my $rc = Git::Libgit2::FFI::git_repository_open(\my $repo, '/path/to/.git');
  check_rc $rc;

=head1 DESCRIPTION

Low-level L<FFI::Platypus> bindings to the C<libgit2> C library, via
L<Alien::Libgit2>.

This module is intentionally close to the C surface. Use L<Git::Native>
for an idiomatic Moo wrapper with RAII handle management.

=head2 init_lib

    init_lib();

Initialise the libgit2 library (wraps C<git_libgit2_init>). Safe to call
repeatedly — libgit2 reference-counts initialisations and returns the new
count, which this returns too. Croaks if the count comes back below C<1>.

=head2 shutdown_lib

    shutdown_lib();

Decrement libgit2's initialisation count (wraps C<git_libgit2_shutdown>) and
return the remaining count. A no-op returning C<0> if L</init_lib> was never
called. Call once per matching L</init_lib>.

=head2 version

    my $string            = version();   # "1.9.0"
    my ($maj, $min, $rev) = version();    # (1, 9, 0)

Return the libgit2 library version (wraps C<git_libgit2_version>). In scalar
context returns a dotted C<"major.minor.revision"> string; in list context
returns the three numeric components.

=head2 check_rc

    my $rc = check_rc( some_libgit2_call(...) );

Pass a libgit2 return code straight through when it is non-negative. On a
negative code, throw the corresponding L<Git::Libgit2::Error> (built from
C<git_error_last>); the exception stringifies to the libgit2 error message.

=head2 oid_from_hex

    my $raw = oid_from_hex('39a3c8...');   # 40 hex chars

Convert a 40-character hex OID into a Perl scalar holding the raw 20 bytes
(wraps C<git_oid_fromstr>). Croaks unless the input is exactly 40 hex digits.

B<Lifetime:> the returned scalar I<is> the OID buffer — libgit2 is handed a
pointer into its PV. Keep the scalar alive for as long as any libgit2 call
still needs the OID.

=head2 oid_to_hex

    my $hex = oid_to_hex($oid_ptr);

Convert a C<git_oid> pointer into its 40-character hex string (wraps
C<git_oid_tostr>).

=head1 EXPORTS

Nothing is exported by default. Functions available on request:
C<init_lib>, C<shutdown_lib>, C<version>, C<check_rc>, C<oid_from_hex>,
C<oid_to_hex>.

Constants, by group: object type (C<GIT_OBJECT_*>), repository init
(C<GIT_REPOSITORY_INIT_BARE>), OID sizes and the abbreviated-OID minimum
(C<GIT_OID_RAWSZ>, C<GIT_OID_HEXSZ>, C<GIT_OID_MINPREFIXLEN>), error codes
(C<GIT_OK>, C<GIT_ERROR>, the
C<GIT_E*> family plus C<GIT_PASSTHROUGH>, C<GIT_ITEROVER>, C<GIT_RETRY>,
C<GIT_TIMEOUT>), the C<git_libgit2_opts> option and config levels
(C<GIT_OPT_SET_SEARCH_PATH>, C<GIT_CONFIG_LEVEL_*>,
C<GIT_CONFIG_HIGHEST_LEVEL>), revwalk sort (C<GIT_SORT_*>), remote
direction (C<GIT_DIRECTION_*>), branch type (C<GIT_BRANCH_*>), tree entry
filemode (C<GIT_FILEMODE_*>) and status flags (C<GIT_STATUS_*>).

The C<:all> tag imports every name listed above.

=head1 SEE ALSO

L<Alien::Libgit2>, L<Git::Native>, L<FFI::Platypus>, L<libgit2|https://libgit2.org/>

=head1 SUPPORT

=head2 Issues

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

=head1 CONTRIBUTING

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

=head1 AUTHOR

Torsten Raudssus <getty@cpan.org>

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus <torsten@raudssus.de> L<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.

=cut