View on
Alessandro Ghedini > Git-Raw > Git::Raw::Repository



Annotate this POD


View/Report Bugs
Module Version: 0.33   Source   Latest Release: Git-Raw-0.74


Git::Raw::Repository - Git repository class


version 0.33


    use Git::Raw;

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

          print "Objects: $received_objects/$total_objecs", "\n";
          print "Received: ", int($received_bytes/1024), "KB", "\n";

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


A Git::Raw::Repository represents a Git repository.

WARNING: The API of this module is unstable and may change without warning (any change will be appropriately documented in the changelog).


init( $path, $is_bare )

Initialize a new repository at $path.

clone( $url, $path, \%opts )

Clone the repository at $url to $path. Valid fields for the %opts hash are:

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.

index( )

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

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.

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:


    $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' => [ '' ]

reset( $target, \%opts )

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

status( [$file, $file, ...] )

Retrieve the status of files in the index and/or working directory. This functions 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" 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".


    my $file_statuses = $repo -> status();
    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. Each element in @objects should either be a Git::Raw::Reference or a Git::Raw::Commit. A minimum of 2 objects should be provided.

merge_analysis( $reference )

Analyzes the given $reference and determines 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".

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

Merge the given $ref into HEAD. This function returns a hash reference with members "up_to_date", "fast_forward" and "id" if the merge was fast-forward. See Git::Raw::Repository->checkout() for valid %checkout_opts values. Valid fields for %merge_opts are


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

      'checkout_strategy' => {
        'force' => 1

ignore( $rules )

Add an ignore rules 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.

diff( [\%opts] )

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

blob( $buffer )

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

branch( $name, $target )

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

branches( )

Retrieve a list of Git::Raw::Branch objects.

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

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

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

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

tags( )

Retrieve the list of Git::Raw::Tag objects representing the repository's annotated Git tags. Lightweight tags are not returned.

stash( $stasher, $msg )

Save the local modifications to a new stash. Shortcut for Git::Raw::Stash->save().

remotes( )

Retrieve the list of Git::Raw::Remote objects.

refs( )

Retrieve the list of Git::Raw::Reference objects.

walker( )

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

path( )

Retrieve the complete path of the repository.

workdir( [$new_dir] )

Retrieve the working directory of the repository. If $new_dir is passed, the working directory of the repository will be set to the directory.

blame( $path )

Retrieve blame information for $path. Returns a Git::Raw::Blame object.

state( )

Determine the state of the repository. One of the following values is returned:

state_cleanup( )

Remove all the metadata associated with an ongoing command like merge, revert, cherry-pick, etc.

is_empty( )

Check if the repository is empty.

is_bare( )

Check if the repository is bare.

is_shallow( )

Check if the repository is a shallow clone.


Alessandro Ghedini <>


Copyright 2012 Alessandro Ghedini.

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 for more information.

syntax highlighting: