/ 
Git-Native-0.005
/ Git::Native::Index

NAME

Git::Native::Index - A libgit2 index (the staging area), read-only

VERSION

version 0.005

SYNOPSIS

my $index = $repo->index;

if ( $index->is_tracked_under('tasks') ) { ... }   # the path question
if ( $index->has_path('tasks/1.md') )    { ... }   # one exact entry
say $index->entrycount;

DESCRIPTION

The repository's index — git's staging area, the list of tracked paths. Wraps git_index*; freed automatically.

Read-only on purpose. The questions this answers are "does the index know this path" and "is anything tracked under this directory"; there is no add / remove / write, so nothing here can stage or unstage anything.

Get one from "index" in Git::Native::Repository, which re-reads the index file before handing it over. What you hold afterwards carries no freshness guarantee in either direction: it does not refresh itself, and it is not a frozen snapshot of the moment you took it either. libgit2 keeps one git_index* per repository and hands that same one to every caller, so any other $repo->index in the process re-reads the file underneath it. Call "reload" when you want the current state; there is no way to pin a past one.

Paths are index paths: relative to the working directory root, with / separators and no leading ./, exactly as git ls-files prints them.

entrycount

say $index->entrycount;

Number of entries in the index, i.e. how many paths git currently tracks.

find

my $pos = $index->find('lib/Git/Native.pm');

The 0-based position of the entry for exactly $path, or undef when the index has no such entry. Positions are into libgit2's sorted entry list and change whenever the index does — useful to tell "found at 0" from "not found", not as a durable handle. Croaks on an undefined or empty path.

Only "not found" comes back undef; any other libgit2 failure throws a Git::Native::Error, so an unreadable index is never mistaken for an untracked path.

find_prefix

my $pos = $index->find_prefix('tasks');

The 0-based position of the first entry whose path starts with the string $prefix, or undef when none does.

This is a raw string prefix with no path semantics: 'tasks' matches 'tasks/1.md' and equally matches 'tasksfoo.txt', because both begin with those five characters. For "is anything tracked under the directory tasks" use "is_tracked_under", which is the path-aware question. Croaks on an undefined or empty prefix — an empty prefix matches the first entry of any non-empty index, which is never the question being asked.

has_path

if ( $index->has_path('README.md') ) { ... }

1 or 0: is exactly $path tracked? The boolean form of "find", and the equivalent of git ls-files --error-unmatch $path succeeding.

has_prefix

$index->has_prefix('tasks');    # true for 'tasksfoo.txt' too

1 or 0 for "find_prefix" — again a string prefix, not a path. Reach for "is_tracked_under" unless you specifically want string matching.

is_tracked_under

if ( $index->is_tracked_under('tasks') ) { ... }

1 or 0: is anything tracked at or below $path? The same question git ls-files -- $path answers, for a file and a directory alike.

A trailing slash on $path is ignored, then the answer is true when $path is itself a tracked file, or when any tracked path begins with $path/. So 'tasks' is true for a repository tracking tasks/1.md, and false for one tracking only tasksfoo.txt — the trap "has_prefix" walks into. Croaks on an undefined or empty path, and on a path that is nothing but slashes.

reload

$index->reload;
$index->reload( force => 1 );

Re-read the index file from disk and return the index. By default libgit2 re-reads only if the file actually changed; force => 1 re-reads unconditionally. This is how a long-lived Index picks up work another process committed or staged in the meantime.

SEE ALSO

Git::Native::Repository, Git::Native::Tree

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.