Provided by: libgit-raw-perl_0.90+ds-2build3_amd64 bug

NAME

       Git::Raw::Remote - Git remote class

VERSION

       version 0.90

SYNOPSIS

           use Git::Raw;

           # open the Git repository at $path
           my $repo = Git::Raw::Repository -> open($path);

           # add a new remote
           my $remote = Git::Raw::Remote -> create($repo, 'origin', $url);

           # connect the remote and set the acquire credentials callback
           $remote -> connect('fetch', {
             'credentials' => sub {
               Git::Raw::Cred -> userpass($usr, $pwd)
             },
           });

           # fetch from the remote and update the local tips
           $remote -> download;
           $remote -> update_tips({
             'update_tips' => sub {
               my ($ref, $a, $b) = @_;
               print "Updated $ref: $a -> $b", "\n";
             }
           });

           # disconnect
           $remote -> disconnect;

           my $empty_repo = Git::Raw::Repository -> new;
           my $anonymous_remote = Git::Raw::Remote -> create_anonymous($repo, $url);
           my $list = $anonymous_remote -> ls;

DESCRIPTION

       A "Git::Raw::Remote" represents a Git remote.

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

METHODS

   create( $repo, $name, $url, [$fetch] )
       Create a remote with the default fetch refspec or $fetch if provided, and add it to the
       repository's configuration.

   create_anonymous( $repo, $url )
       Create a remote in memory (anonymous).

   load( $repo, $name )
       Load an existing remote. Returns a Git::Raw::Remote object if the remote was found,
       otherwise "undef".

   delete( $repo, $name )
       Delete an existing remote.

   owner( )
       Retrieve the Git::Raw::Repository owning the remote.

   default_branch( )
       Retrieve the default branch of remote repository, that is, the branch which HEAD points
       to. If the remote does not support reporting this information directly, it performs the
       guess as git does, that is, if there are multiple branches which point to the same commit,
       the first one is chosen. If the master branch is a candidate, it wins. If the information
       cannot be determined, this function will return "undef". Note, this function should only
       be called after the remote has established a connection.

   name( )
       Retrieve the name of the remote.

   rename( $repo, $old_name, $new_name, [ \@problems ] )
       Rename a remote. Non-default refspecs cannot be renamed and will be stored in @problems if
       provided.

   url( [ $url ] )
       Retrieve the URL of the remote. If $url is passed, the remote's URL will be updated and
       returned.

   pushurl( [ $url ] )
       Retrieve the push URL for the remote. If $url is passed, the remote's push URL will be
       updated and returned.

   add_fetch( $spec )
       Add a fetch spec to the remote.

   add_push( $spec )
       Add a push spec to the remote.

   refspec_count( )
       Retrieve the refspec count.

   refspecs( )
       Retrieve the remote's refspecs. Returns a list of Git::Raw::RefSpec objects.

   ls( )
       Retrieve the list of refs at the remote. Returns a hash reference where the key is the
       name of the reference, and the value is a hash reference containing the following values:

       •   "local"

           Whether the reference exists locally.

       •   "id"

           The OID of the reference.

       •   "lid"

           The local OID of the reference (optional).

   fetch( [ \%fetch_opts, [ \@refspecs ] ] )
       Download new data and update tips. Convenience function to connect to a remote, download
       the data, disconnect and update the remote-tracking branches.  @refspecs is an optional
       list of refspecs to use for the negotiation with the server to determine the missing
       objects that need to be downloaded.  Valid fields for the %fetch_opts hash are:

       •   "callbacks"

           See "CALLBACKS" in CALLBACKS.

       •   "prune"

           NOT IMPLEMENTED.

       •   "update_fetchead"

           NOT IMPLEMENTED.

       •   "download_tags"

           NOT IMPLEMENTED.

       •   "custom_headers"

           NOT IMPLEMENTED.

   push( \@refspecs, [ \%push_opts ] )
       Perform all the steps of a push, including uploading new data and updating the remote
       tracking-branches. Valid fields for the %push_opts hash are:

       •   "callbacks"

           See "CALLBACKS" in CALLBACKS.

       •   "custom_headers"

           NOT IMPLEMENTED.

   connect( $direction, [ \%callbacks ] )
       Connect to the remote. The $direction should either be "fetch" or "push".

   disconnect( )
       Disconnect the remote.

   download( [ \%fetch_opts, [ \@refspecs ] ] )
       Download the remote packfile. See "Git::Raw::Remote->fetch()" for valid %fetch_opts and
       @refspecs values.

   upload( \@refspecs, [ \%push_opts ] )
       Create a packfile and send it to the server. @refspecs is a list of refspecs to use for
       the negotiation with the server to determine the missing objects that need to be uploaded.

   prune( [ \%callbacks ] )
       Prune tracking refs that are no longer present on remote.

   update_tips( [ \%callbacks ] )
       Update the tips to the new status.

   is_connected( )
       Check if the remote is connected.

CALLBACKS

   credentials
       The callback to be called any time authentication is required to connect to the remote
       repository. The callback receives a string $url containing the URL of the remote, the
       $user extracted from the URL and a list of supported authentication $types. The callback
       should return either a Git::Raw::Cred object or alternatively "undef" to abort the
       authentication process. $types may contain one or more of the following:

       •   "userpass_plaintext"

           Plaintext username and password.

       •   "ssh_key"

           A SSH key from disk

       •   "ssh_custom"

           A SSH key with a custom signature function.

       •   "ssh_interactive"

           Keyboard-interactive based SSH authentication

       •   "username"

           Username-only credential information.

       •   "default"

           A key for NTLM/Kerberos default credentials.

       Note: this callback may be invoked more than once.

   certificate_check
       Callback to be invoked if cert verification fails. The callback receives a
       Git::Raw::Cert::X509 or Git::Raw::Cert::HostKey object, a truthy value $valid and $host.
       This callback should return a negative number to abort.

   sideband_progress
       Textual progress from the remote. Text sent over the progress side-band will be passed to
       this function (this is the 'counting objects' output or any other information the remote
       sends). The callback receives a string $msg containing the progress information.

   transfer_progress
       During the download of new data, this will be regularly called with the current count of
       progress done by the indexer. The callback receives a Git::Raw::TransferProgress object.

   update_tips
       Each time a reference is updated locally, this function will be called with information
       about it. The callback receives a string containing the reference $ref of the reference
       that was updated, and the two OID's $a before and after $b the update. $a will be "undef"
       if the reference was created, likewise $b will be "undef" if the reference was removed.

   push_transfer_progress
       During the upload of new data, this will regularly be called with the transfer progress.
       The callback receives the following integers: $current, $total and $bytes.

   push_update_reference
       For each of the updated references, this will be called with a status report for the
       reference. The callback receives $ref and $msg as strings. If $msg is defined, the
       reference mentioned in $ref has not been updated.

   push_negotation
       The callbacks receives a list of updates that will be sent to the destination.  Each items
       consists of $src_refname, $dst_refname as well as their OIDs, $src and $dst. This callback
       should return a negative number to abort.

   pack_progress
       During the packing of new data, this will regularly be called with the progress of the
       pack operation. Be aware that this is called inline with pack building operations, so
       performance may be affected. The callback receives the following integers: $stage,
       $current and $total.

AUTHOR

       Alessandro Ghedini <alexbio@cpan.org>

       Jacques Germishuys <jacquesg@cpan.org>

LICENSE AND COPYRIGHT

       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 http://dev.perl.org/licenses/ for more information.