/ 
Git-Native-0.005
/ Git::Native::Oid

NAME

Git::Native::Oid - A libgit2 OID (20-byte SHA-1)

VERSION

version 0.005

SYNOPSIS

my $oid = Git::Native::Oid->from_hex('abcd...');
say $oid;          # full hex
say $oid->short;   # 7 chars
$oid->ptr;         # C pointer for libgit2

DESCRIPTION

A SHA-1 OID. Holds the raw 20 bytes; everything else is derived. The raw scalar is the anchor for any pointer libgit2 reads it through - keep the Oid alive as long as the pointer is in use.

An Oid is a plain value object with no libgit2 handle behind it, so it outlives the repository, reference or commit it came from. Methods all over Git::Native that take an OID accept either an Oid or a 40-character hex string.

Two operators are overloaded. Stringification ("") gives the full hex form, so an Oid interpolates and prints without an explicit ->hex:

say "commit $oid";   # 35104eb6815e52f24b06c95cbc53e95943cb532b

and eq compares on hex against either another Oid or a plain hex string, which is what makes $ref->target eq $known_sha work. The comparison is always on the full 40 characters — $oid eq $oid->short is false, an abbreviation never matches.

A malformed OID croaks; it does not throw a Git::Native::Error. Since every Oid|hex argument in Git::Native is converted here, that applies to the whole convenience — $repo->object($hex), $ref->set_target($hex), $walker->push_oid($hex), $builder->insert( oid => $hex ) and the rest all croak on a string that is not 40 hex characters. See "from_hex" for why.

raw

my $bytes = $oid->raw;   # 20 binary bytes

The OID as 20 binary bytes, not hex — length is always 20 and the bytes are not printable. Required at construction; the other forms are derived from it.

from_hex

my $oid = Git::Native::Oid->from_hex('35104eb6815e52f24b06c95cbc53e95943cb532b');

Build an Oid from a full 40-character hex string. Anything shorter dies — this is not abbreviation-aware, and resolving a short prefix against a repository is a different operation: "object_by_prefix" in Git::Native::Repository, which the croak points at.

The failure is a Carp::croak — a plain string blaming the caller's line, not a Git::Native::Error — and that is deliberate rather than an oversight:

A Git::Native::Error carries a ->code that came out of libgit2. A string that is not 40 hex characters never reaches libgit2 at all (git_oid_fromstr is not called), so there is no code to report; a synthetic one would be the only fabricated ->code in the distribution, with a ->klass naming no libgit2 subsystem.

The code it would have to fabricate is GIT_EINVALIDSPEC, which libgit2 does raise for real — for a refname or refspec it rejects. Sharing it would make $err->is_invalid_spec ambiguous inside a single call: after $repo->reference_create($name, $hex) the caller could no longer tell a malformed refname (libgit2's verdict on the repository input) from its own typo in the OID string. That is the same separation "object_by_prefix" in Git::Native::Repository keeps for is_ambiguous, and the same reason its own argument checks croak.

So catch it with eval when the hex came from outside the program, exactly as for any other argument the caller got wrong. There is no ->code to branch on because libgit2 never said anything about it.

from_raw

my $oid = Git::Native::Oid->from_raw($twenty_bytes);

Build an Oid from exactly 20 binary bytes; croaks on any other length, and on undef. A caller error like "from_hex"'s, and a croak for the same reason.

from_ptr

my $oid = Git::Native::Oid->from_ptr($git_oid_ptr);

Build an Oid from a git_oid * that libgit2 handed out. The 20 bytes are copied, so the result stays valid after the handle it came from is freed. Internal plumbing — wrappers use it, callers rarely need it.

hex

say $oid->hex;   # 35104eb6815e52f24b06c95cbc53e95943cb532b

The full 40-character lowercase hex form.

short

say $oid->short;      # 35104eb
say $oid->short(10);  # 35104eb681

The first $n hex characters, 7 by default. Purely a prefix of hex — no uniqueness check against the repository, unlike git rev-parse --short.

ptr

Git::Libgit2::FFI::some_call( $oid->ptr );

A C pointer to the raw bytes, for passing into libgit2. It points into the Oid's own scalar, so the Oid has to stay alive for as long as the pointer is in use.

SEE ALSO

Git::Native::Reference, Git::Native::Commit

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.