/ 
Git-Native-0.005
/ Git::Native::Branch

NAME

Git::Native::Branch - A libgit2 branch (thin wrapper over git_reference)

VERSION

version 0.005

SYNOPSIS

my $b = $repo->branch('main');
say $b->name;          # 'main'
say $b->refname;       # 'refs/heads/main'
say $b->target->hex;   # commit OID
$b->rename('trunk');

DESCRIPTION

Wraps a libgit2 branch (which is really a git_reference under refs/heads/* or refs/remotes/*). Constructed by "branch" in Git::Native::Repository and "branches" in Git::Native::Repository. A Branch keeps its repository alive for as long as it is in scope.

The same ref is reachable as a Git::Native::Reference through "reference" in Git::Native::Repository; this class adds the branch-specific calls (name, is_head, rename) on top.

type

my $b = $repo->branch('origin/main', type => Git::Native::Branch::GIT_BRANCH_REMOTE);

Which namespace the branch was looked up in — GIT_BRANCH_LOCAL (1, the default), GIT_BRANCH_REMOTE (2) or GIT_BRANCH_ALL (3). It selects the lookup and is what is_local / is_remote report back.

name

say $b->name;   # 'main', or 'origin/main' for a remote branch

The branch name with its namespace prefix stripped: refs/heads/main gives main, refs/remotes/origin/main gives origin/main — the remote name stays part of it.

refname

say $b->refname;   # refs/heads/main

The full reference name behind the branch.

target

say $b->target;   # commit OID

The Git::Native::Oid the branch points at, or undef in the (unusual) case of a symbolic branch ref.

is_head

say $b->is_head;   # 1 when HEAD points here

1 when the repository's HEAD resolves to this branch, 0 otherwise. Always 0 while HEAD is detached, since a detached HEAD points at no branch.

is_local / is_remote

$repo->branch('main')->is_local;   # 1

1 or 0 from the type the branch was looked up with, not from the refname — the local/remote distinction is decided when "branch" in Git::Native::Repository or "branches" in Git::Native::Repository selects the namespace to search.

delete

$repo->branch('stale')->delete;

Delete the branch reference and return the invocant. Deleting the branch HEAD points at is rejected by libgit2 with a Git::Native::Error.

rename

my $renamed = $b->rename('trunk');
my $forced  = $b->rename('trunk', force => 1);

Move the branch to a new name and return the renamed branch as a new object; the invocant still reports the old refname, having been made from the pre-rename handle. Throws when the target name already exists unless force is set.

SEE ALSO

Git::Native::Repository, Git::Native::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.