Git::R...sitory(3pm)

📦

version 0.90 · 7 versions

💖 Git::Raw::Repository 💖

okay so bestie, this is the manual for Git::Raw::Repository from the User Contributed Perl Documentation. It's giving Git repository class energy, and we're gonna go through every single detail together. periodt. 💅

✨ NAME ✨

Git::Raw::Repository — it's literally a Git repository class, no cap. 🦋

🌸 VERSION 🌸

version 0.90 — that's the vibe check, bestie. ✨

🎀 SYNOPSIS 🎀

okay so like, here's a whole mood of how you use this thing:

           use Git::Raw;

           # clone a Git repository
           my $url  = 'git://github.com/jacquesg/p5-Git-Raw.git';
           my $callbacks = {
             'transfer_progress' => sub {
               my ($total_objects, $received_objects, $local_objects, $total_deltas,
                 $indexed_deltas, $received_bytes) = @_;

               print "Objects: $received_objects/$total_objects", "\n";
               print "Received: ", int($received_bytes/1024), "KB", "\n";
             }
           };
           my $repo = Git::Raw::Repository -> clone($url, 'p5-Git-Raw', {}, {
             'callbacks' => $callbacks
           });

           # print all the tags of the repository
           foreach my $tag ($repo -> tags) {
             say $tag -> name;
           }

           # merge a reference
           my $ref = Git::Raw::Reference -> lookup('HEAD', $repo);
           $repo -> merge ($ref);

           my @conflicts = $repo -> index -> conflicts;
           print "Got ", scalar (@conflicts), " conflicts!\n";

💜 DESCRIPTION 💜

A Git::Raw::Repository represents a Git repository. That's the whole mood. 💅

WARNING: The API of this module is unstable and may change without warning (any change will be appropriately documented in the changelog). No cap, this is important — it might change on you, bestie. 😭

👑 METHODS 👑

🧚 init( $path, $is_bare )

Initialize a new repository at $path. The full signature is init( $path, $is_bare ). Slay. 💖

🦋 clone( $url, $path, %opts, [%fetch_opts, %checkout_opts])

Clone the repository at $url to $path. Here's the tea on valid fields for the %opts hash:

bare — If true (default is false) create a bare repository. 💅
checkout_branch — The name of the branch to checkout (default is to use the remote's HEAD).
disable_checkout — If true (default is false) files will not be checked out after the clone completes.
callbacks —
- remote_create — Remote customization callback. If a non-default remote is required, i.e. a remote with a remote name other than 'origin', this callback should be used. The callback receives a Git::Raw::Repository object, a string containing the default name for the remote, typically 'origin', and a string containing the URL of the remote. This callback should return a Git::Raw::Remote object. The returned object and the repository object passed to this callback are ephemeral. Note: Do not take any references to it, as it may be freed internally. 😱

See "Git::Raw::Remote->fetch()" for valid %fetch_opts values and "Git::Raw::Repository->checkout()" for valid %checkout_opts values.

🌈 open( $path )

Open the repository at $path.

🍓 discover( $path )

Discover the path to the repository directory given a subdirectory.

✨ new( )

Create a new repository with neither backends nor config object.

💫 config( )

Retrieve the default Git::Raw::Config of the repository.

🫶 commondir( )

Get the path of the shared common directory for this repository.

🧚 is_worktree( )

Check if the repository is a linked work tree.

🎀 index( [$new_index] )

Retrieve the index of the repository. If $new_index is passed, it will be used as the index of the repository. If $new_index is undef the index associated with the repository will be disassociated. Returns a Git::Raw::Index object or undef if index has been disassociated as part of the call.

🦋 odb( [$new_odb] )

Retrieve the object database of the repository. If $odb is passed, it will be used as the object database. Returns a Git::Raw::Odb object.

💖 head( [$new_head] )

Retrieve the Git::Raw::Reference pointed by the HEAD of the repository. If the Git::Raw::Reference $new_head is passed, the HEAD of the repository will be changed to point to it.

🌸 head_for_worktree( $worktree )

Retrieve the Git::Raw::Reference pointed by the HEAD of $worktree.

🔥 detach_head( $commitish )

Make the repository HEAD point directly to a commit. $commitish should be peelable to a Git::Raw::Commit object, that is, it should be a Git::Raw::Commit or Git::Raw::Reference object, or alternatively a commit id or commit id prefix.

💅 lookup( $id )

Retrieve the object corresponding to $id.

🦋 checkout( $object, %opts )

Updates the files in the index and working tree to match the content of $object. Valid fields for the %opts hash are:

checkout_strategy — Hash representing the desired checkout strategy. Valid fields are:
- none — Dry-run checkout strategy. It doesn't make any changes, but checks for conflicts.
- force — Take any action to make the working directory match the target (pretty much the opposite of none).
- safe_create — Recreate missing files.
- safe — Make only modifications that will not lose changes (to be used in order to simulate git checkout).
- allow_conflicts — Apply safe updates even if there are conflicts.
- remove_untracked — Remove untracked files from the working directory.
- remove_ignored — Remove ignored files from the working directory.
- update_only — Only update files that already exist (files won't be created or deleted).
- dont_update_index — Do not write the updated files' info to the index.
- dont_remove_existing — Don not overwrite existing files or folders.
- dont_write_index — Prevent writing of the index upon completion.
- no_refresh — Do not reload the index and git attrs from disk before operations.
- skip_unmerged — Skip files with unmerged index entries, instead of treating them as conflicts.
notify — Notification flags for the notify callback. A list of the following options:
- conflict — Notifies about conflicting paths.
- dirty — Notifies about files that don't need an update but no longer match the baseline. Core git displays these files when checkout runs, but won't stop the checkout.
- updated — Notification on any file changed.
- untracked — Notification about untracked files.
- ignored — Notifies about ignored files.
- all — All of the above.
callbacks — Hash containing progress and notification callbacks. Valid fields are:
- notify — This callback is called for each file matching one of the notify options selected. It runs before modifying any files on disk. This callback should return a non-zero value should the checkout be cancelled. The callback receives a string containing the path of the file $path and an array reference containing the reason $why.
- progress — The callback to be invoked as a file is checked out. The callback receives a string containing the path of the file $path, an integer $completed_steps and an integer $total_steps.
paths — An optional array representing the list of files that should be checked out. If paths is not specified, all files will be checked out (default).
our_label — The name of the "our" side of conflicts.
their_label — The name of the "their" side of conflicts.
ancestor_label — The name of the common ancestor side of conflicts.
target_directory — Alternative checkout path to the working directory.

Example:

           $repo -> checkout($repo -> head -> target, {
             'checkout_strategy' => { 'safe'  => 1 },
             'notify'    => [ 'all' ],
             'callbacks' => {
                'notify' => sub {
                  my ($path, $why) = @_;

                  print "File: $path: ", join(' ', @$why), "\n";
                },
                'progress' => sub {
                   my ($path, $completed_steps, $total_steps) = @_;

                   print "File: $path", "\n" if defined ($path);
                   print "Progress: $completed_steps/$total_steps", "\n";
                }
             },
             'paths' => [ 'myscript.pl' ]
           });

🌸 reset( $target, %opts )

Reset the current HEAD to the given commit. Valid fields for the %opts hash are:

type — Set the type of the reset to be performed. Valid values are: soft (the head will be moved to the commit), mixed (trigger a soft reset and replace the index with the content of the commit tree) or hard (trigger a mixed reset and the working directory will be replaced with the content of the index).
paths — List of entries in the index to be updated from the target commit tree. This is particularly useful to implement git reset HEAD -- file file behaviour. Note, if this parameter is specified, a value of mixed will be used for type (setting type to soft or hard has no effect).

🦋 status( %opts, [$file, $file, ...] )

Retrieve the status of files in the index and/or working directory. This function returns a hash reference with an entry for each $file, or all files if no file parameters are provided. Each $file entry has a list of flags, which may include: index_new, index_modified, index_deleted, index_renamed, worktree_new, worktree_modified, worktree_deleted, worktree_renamed, worktree_unreadable, conflicted and ignored.

If $file has been renamed in either the index or worktree or both, $file will also have a corresponding entry index and/or worktree, containing the previous filename old_file.

Valid fields for the %opts hash are:

flags — Flags for the status. Valid values include:
- include_untracked — Callbacks should be made on untracked files. These will only be made if the workdir files are included in the $show option.
- include_ignored — Callbacks should be made on ignored files. These will only be made if the ignored files get callbacks.
- include_unmodified — Include even unmodified files.
- exclude_submodules

…still deep inside that flags list, we didn't go anywhere 💅

Submodules get skipped, bestie. This only applies if there are no pending typechanges to the submodule (either from or to another type).
recurse_untracked_dirs — all files in untracked directories should be included 🦋. Normally, if an entire directory is new, then just the top-level directory is included (with a trailing slash on the entry name). This flag includes all of the individual files in the directory instead.
disable_pathspec_match — each $file you specify should be treated as a literal path, and not as a pathspec pattern. No pattern matching, just the exact path you typed ✨
recurse_ignored_dirs — the contents of ignored directories should be included in the status 🎀. This is like doing git ls-files -o -i --exclude-standard with core git.
renames_head_to_index — rename detection should be processed between the head and the index.
renames_index_to_workdir — rename detection should be run between the index and the working directory.
sort_case_sensitively — override the native case sensitivity for the file system and force the output to be in case-sensitive order 🔤
sort_case_insensitively — override the native case sensitivity for the file system and force the output to be in case-insensitive order.
renames_from_rewrites — rename detection should include rewritten files.
no_refresh — bypass the default status behavior of doing a "soft" index reload (i.e. reloading the index data if the file on disk has been modified outside Git::Raw) 🙈
update_index — refresh the stat cache in the index for files that are unchanged but have out-of-date stat information in the index. It will result in less work being done on subsequent calls to status 🔥. This is mutually exclusive with the no_refresh option — pick one, bestie.
include_unreadable — include unreadable files.
include_unreadable_as_untracked — include unreadable files as untracked files.

show — one of the following values (defaults to index_and_worktree):
- index_and_worktree
- index
- worktree

Example 👇

my $opts = {
  'flags' => {
    'include_untracked'        => 1,
    'renames_head_to_index'    => 1,
    'renames_index_to_workdir' => 1,
  },
  'show' => 'index_and_worktree'
};
my $file_statuses = $repo -> status($opts);
while (my ($file, $status) = each %$file_statuses) {
  my $flags = $status -> {'flags'};
  print "File: $file: Status: ", join (' ', @$flags), "\n";

  if (grep { $_ eq 'index_renamed' } @$flags) {
    print "Index previous filename: ",
    $status -> {'index'} -> {'old_file'}, "\n";
  }

  if (grep { $_ eq 'worktree_renamed' } @$flags) {
    print "Worktree previous filename: ",
    $status -> {'worktree'} -> {'old_file'}, "\n";
  }
}

`merge_base( @objects )`

Find the merge base between @objects 🧚. Every element in @objects should be peelable to a Git::Raw::Commit object — translation: it should be a Git::Raw::Commit or Git::Raw::Reference object, or alternatively a commit id or commit id prefix. That's the whole gig.

`merge_analysis( $reference )`

Analyzes the given $reference and figures out the opportunities for merging them into the HEAD of the repository 👑. This function returns an array reference with optional members normal, up_to_date, fast_forward and/or unborn.

normal — a "normal" merge. Both HEAD and the given merge input have diverged from their common ancestor. The divergent commits must be merged.
up_to_date — all given merge inputs are reachable from HEAD, meaning the repository is up-to-date and no merge needs to be performed. Slay, nothing to do 🎀
fast_forward — the given merge input is a fast-forward from HEAD and no merge needs to be performed. Instead, the given merge input may be checked out.
unborn — the HEAD of the current repository is "unborn" and does not point to a valid commit. No merge can be performed, but the caller may wish to simply set HEAD to the target commit(s).

`merge( $ref, [\%merge_opts, \%checkout_opts])`

Merge the given $ref into HEAD, writing the results into the working directory 💖. Any changes are staged for commit and any conflicts are written to the index. The index should be inspected for conflicts after this method completes and any conflicts should be resolved 😭. At this stage a commit may be created to finalise the merge.

flags — merge flags. Valid values include:
- find_renames — detect renames.
file_flags — see "Git::Raw::Index->merge()" for options.
favor — specify content automerging behaviour. Valid values are ours, theirs, and union.
rename_threshold — similarity metric for considering a file renamed (default is 50).
target_limit — maximum similarity sources to examine (overrides the merge.renameLimit configuration entry) (default is 200).

Example 👇

my $branch = Git::Raw::Branch -> lookup($repo, 'branch', 1);
my $analysis = $repo -> merge_analysis($branch);
my $merge_opts = {
  'favor' => 'theirs'
};
my $checkout_opts = {
  'checkout_strategy' => {
    'force' => 1
  }
};
$repo -> merge($branch1, $merge_opts, $checkout_opts);

`ignore( $rules )`

Add an ignore rule to the repository 🌸. The format of the rules is the same one of the .gitignore file (see the gitignore(5) manpage). Example 👇

$repo -> ignore("*.o\n");

`path_is_ignored( $path )`

Checks the ignore rules to see if they would apply to the given file 🫶. This indicates if the file would be ignored regardless of whether the file is already in the index or committed to the repository. Vibe check, but for ignore rules.

`diff( [\%diff_opts] )`

Compute the Git::Raw::Diff between the repo's default index and another tree ✨. Valid fields for the %diff_opts hash are:

tree — if provided, the diff is computed between tree and the repo's default index. The default is the repo's working directory.
flags — flags for generating the diff. Valid values include:
- reverse — reverse the sides of the diff.
- include_ignored — include ignored files in the diff.
- include_typechange — enable the generation of typechange delta records.
- recurse_ignored_dirs — even if include_ignored is specified, an entire ignored directory will be marked with only a single entry in the diff. This flag adds all files under the directory as ignored entries, too.
- include_untracked — include untracked files in the diff.
- recurse_untracked_dirs — even if include_untracked is specified, an entire untracked directory will be marked with only a single entry in the diff (core git behaviour). This flag adds all files under untracked directories as untracked entries, too.
- ignore_filemode — ignore file mode changes.
- ignore_case — use case insensitive filename comparisons.
- ignore_submodules — treat all submodules as unmodified.
- ignore_whitespace — ignore all whitespace.
- ignore_whitespace_change — ignore changes in amount of whitespace.
- ignore_whitespace_eol — ignore whitespace at end of line.
- skip_binary_check — disable updating of the binary flag in delta records. This is useful when iterating over a diff if you don't need hunk and data callbacks and want to avoid having to load file completely.
- enable_fast_untracked_dirs — when diff finds an untracked directory, to match the behavior of core git, it scans the contents for ignored and untracked files. If all contents are ignore, then the directory is ignored. If any contents are not ignored, then the directory is untracked. This is extra work that may not matter in many cases 💀. This flag turns off that scan and immediately labels an untracked directory as untracked (changing the behavior to not match core git).
- show_untracked_content — include the content of untracked files. This implies include_untracked.
- show_unmodified — include the names of unmodified files.
- patience — use the "patience diff" algorithm.
- minimal — take extra time to find minimal diff.
- show_binary — include the necessary deflate / delta information so that git apply can apply given diff information to binary files.
- force_text — treat all files as text, disabling binary attributes and detection.
- force_binary — treat all files as binary, disabling text diffs.
prefix
- a — the virtual "directory" to prefix to old file names in hunk headers. (Default is a.)
- b — the virtual "directory" to prefix to new file names in hunk headers. (Default is b.)
context_lines — the number of unchanged lines that define the boundary of a hunk (and to display before and after)
interhunk_lines — the maximum number of unchanged lines between hunk boundaries before the hunks will be merged into a one.
paths — a list of paths to constrain diff.

`blob( $buffer )`

Create a new Git::Raw::Blob. Shortcut for Git::Raw::Blob->create(). Obsessed 🎀

`branch( $name, $target )`

Create a new Git::Raw::Branch. Shortcut for Git::Raw::Branch->create().

`branches( [$type] )`

Grab a list of Git::Raw::Branch objects, bestie 💜 The $type you hand over can be "local", "remote" or "all" — pick your fighter fr fr.

`commit( $msg, $author, $committer, \@parents, $tree [, $update_ref ] )`

Make a brand new Git::Raw::Commit ✨ It's just a shortcut for Git::Raw::Commit->create(), so you know it's lowkey the same thing with a nicer outfit 💅

`tag( $name, $msg, $tagger, $target )`

Create a fresh Git::Raw::Tag 🎀 Shortcut for Git::Raw::Tag->create(). Iconic behaviour honestly.

`tags( [$type] )`

Returns the list of annotated and/or lightweight tag objects 🏷️ Your $type can be "all", "annotated" or "lightweight". Not me being able to filter tags, we love a flexible queen 👑

`stash( $repo, $msg )`

Save your local modifications off into a new stash 🙈 Shortcut for Git::Raw::Stash->save(). Your messy WIP? Hidden. Your working tree? Clean. Main character energy.

`remotes( )`

Get the list of Git::Raw::Remote objects 🌍

`refs( )`

Get the list of Git::Raw::Reference objects ⭐

`walker( )`

Create a new Git::Raw::Walker 🚶‍♀️🚶 Shortcut for Git::Raw::Walker->create(). Go take a little walk through your history, you deserve it.

`path( )`

Retrieves the complete path of the repository 📍 no cap, the whole thing.

`workdir( [$new_dir] )`

Retrieves the working directory of the repository 🗂️ And if you pass $new_dir, the repository's working directory gets set to that directory. Two jobs, one method, she's doing both 💖

`blame( $path )`

Pulls blame info for $path 👀💀 Returns a Git::Raw::Blame object. Time to find out who wrote that line, iykyk.

`cherry_pick( $commit, [\%merge_opts, \%checkout_opts, $mainline] )`

Cherry-pick that $commit, producing changes in the index and the working directory 🍒✨ Peep Git::Raw::Repository->merge() for the valid %merge_opts and %checkout_opts values — that's where the deets live. And for merge commits, $mainline specifies the parent.

`revert( $commit, [\%merge_opts, \%checkout_opts, $mainline] )`

Revert the given $commit, producing changes in the index and the working directory ↩️ Same deal as above: check Git::Raw::Repository->merge() for valid %merge_opts and %checkout_opts values. For merge commits, $mainline specifies the parent. Undoing things is self-care, periodt.

`revparse( $spec )`

Parses the revision string $spec to for "from", "to" and "intent" 🔍 Returns a list of objects when you're in list context, and the number of objects parsed from $spec when you're in scalar context.

my ($from, $to) = $repo -> revparse('HEAD~..HEAD');
print "Range is $from -> $to", "\n";

`state( )`

Figure out what state the repo is in 🫶 One of these values comes back:

"none" — Normal state. Everything is chill ✨
"merge" — Repository is in a merge.
"revert" — Repository is in a revert.
"cherry_pick" — Repository is in a cherry-pick 🍒
"bisect" — Repository is bisecting.
"rebase" — Repository is rebasing.
"rebase_interactive" — Repository is in an interactive rebase.
"rebase_merge" — Repository is in an rebase merge.
"apply_mailbox" — Repository is applying patches 📬
"mailbox_or_rebase" — Repository is applying patches or rebasing.

`state_cleanup( )`

Removes all the metadata associated with an ongoing command like merge, revert, cherry-pick, etc. 🧹 Big cleanup energy. Wipe the slate, start fresh, we're healing 💅

`message( )`

Retrieves the content of git's prepared message, i.e. .git/MERGE_MSG 💌

`is_empty( )`

Checks if the repository is empty 🕳️

`is_bare( )`

Checks if the repository is bare 👙

`is_shallow( )`

Checks if the repository is a shallow clone 🌊

`is_head_detached( )`

Checks if the repository's HEAD is detached — that is, it points directly to a commit 😭 Your HEAD is out here with no branch to hold onto, free-floating, unbothered, no thoughts.

🌈 AUTHOR 🌈

Alessandro Ghedini <alexbio@cpan.org> 💖

Jacques Germishuys <jacquesg@cpan.org> 💖

👑 LICENSE AND COPYRIGHT 👑

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

And that's a wrap, bestie 🎀 This lil tutorial came to you from perl v5.42.3, dated 2026-08-19, and it lives its life as Git::R...sitory(3pm). Go forth and slay your git objects 💅🦋🌸

📦 where this page comes from

ubuntu stonking: libgit-raw-perl 0.90+ds-3build3 · Artistic-1.0-Perl OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms