/ 
Git-Native-0.005
/ Git::Native::Reference

NAME

Git::Native::Reference - A Git reference (branch, tag, HEAD)

VERSION

version 0.005

SYNOPSIS

my $ref = $repo->reference('refs/heads/main');
say $ref->name;       # refs/heads/main
say $ref->shorthand;  # main
say $ref->target;     # OID
$ref->delete;

my $head = $repo->reference('HEAD');
say $head->symbolic_target;   # refs/heads/main
say $head->resolve->target;   # OID HEAD points at

DESCRIPTION

A Git reference. Direct refs carry an oid target; symbolic refs carry a symbolic_target (a refname) and resolve to a direct ref.

Read accessors: name, shorthand, target, symbolic_target, is_symbolic, is_branch, is_remote, is_tag.

Mutators return a fresh Reference: set_target (direct refs), symbolic_set_target (symbolic refs), plus delete.

References are obtained from a Git::Native::Repository and keep it alive: the repository handle is not freed while any reference taken from it is still in scope.

name

say $ref->name;   # refs/heads/main

The full reference name.

shorthand

say $ref->shorthand;   # main

The short form libgit2 derives from the name — refs/heads/main becomes main. HEAD has no prefix to strip and stays HEAD.

target

my $oid = $ref->target;

The Git::Native::Oid a direct reference points at, or undef for a symbolic one (HEAD normally is symbolic) — use symbolic_target for those, or resolve first and take the target of the result. On an annotated tag ref this is the OID of the tag object, not of the commit it tags; $repo->object on it returns a Git::Native::Tag.

symbolic_target

say $repo->reference('HEAD')->symbolic_target;   # refs/heads/main

The refname a symbolic reference points at, or undef for a direct one. The mirror image of target: exactly one of the two is defined. The named ref need not exist — that is precisely the unborn-HEAD state of a fresh repository.

is_symbolic

if ( $ref->is_symbolic ) { ... }

1 when the reference points at another refname, 0 when it points at an OID.

is_branch / is_remote / is_tag

$repo->reference('refs/heads/main')->is_branch;   # 1

Where the reference lives, decided by its name: refs/heads/*, refs/remotes/*, refs/tags/*. Each returns 1 or 0, and HEAD is none of the three.

resolve

my $direct = $repo->reference('HEAD')->resolve;
say $direct->name;     # refs/heads/main
say $direct->target;   # the commit OID

Follow symbolic references until a direct one is reached and return that as a fresh Reference. The invocant keeps its own handle and stays usable. A reference that is already direct resolves to an equivalent Reference.

set_target

my $moved = $ref->set_target($oid, message => 'rewind one commit');

Repoint a direct reference at $oid (a Git::Native::Oid or a 40-character hex string) and return the updated reference as a new object — the invocant keeps reporting the old value, it is a snapshot of the handle it was created with. message goes into the reflog. Throws a Git::Native::Error on a symbolic reference ("cannot set OID on symbolic reference"); symbolic_set_target is the one to use there.

symbolic_set_target

$repo->reference('HEAD')->symbolic_set_target('refs/heads/topic');

The counterpart for symbolic references: repoint at another refname (which may be one that does not exist yet) and return the updated reference as a new object. message goes into the reflog. Throws a Git::Native::Error on a direct reference.

delete

$repo->reference('refs/heads/stale')->delete;

Delete the reference from the repository and return the invocant. The Perl object stays alive and its accessors keep answering out of the handle it already holds, so what you have afterwards is a snapshot of a ref that is no longer there.

SEE ALSO

Git::Native::Repository, Git::Native::Branch, Git::Native::Oid

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.