.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Git::Raw::Remote 3pm"
.TH Git::Raw::Remote 3pm "2019-01-12" "perl v5.28.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Git::Raw::Remote \- Git remote class
.SH "VERSION"
.IX Header "VERSION"
version 0.79
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    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, \*(Aqorigin\*(Aq, $url);
\&
\&    # connect the remote and set the acquire credentials callback
\&    $remote \-> connect(\*(Aqfetch\*(Aq, {
\&      \*(Aqcredentials\*(Aq => sub {
\&        Git::Raw::Cred \-> userpass($usr, $pwd)
\&      },
\&    });
\&
\&    # fetch from the remote and update the local tips
\&    $remote \-> download;
\&    $remote \-> update_tips({
\&      \*(Aqupdate_tips\*(Aq => sub {
\&        my ($ref, $a, $b) = @_;
\&        print "Updated $ref: $a \-> $b", "\en";
\&      }
\&    });
\&
\&    # 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;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
A \f(CW\*(C`Git::Raw::Remote\*(C'\fR represents a Git remote.
.PP
\&\fB\s-1WARNING\s0\fR: The \s-1API\s0 of this module is unstable and may change without warning
(any change will be appropriately documented in the changelog).
.SH "METHODS"
.IX Header "METHODS"
.ie n .SS "create( $repo, $name, $url, [$fetch] )"
.el .SS "create( \f(CW$repo\fP, \f(CW$name\fP, \f(CW$url\fP, [$fetch] )"
.IX Subsection "create( $repo, $name, $url, [$fetch] )"
Create a remote with the default fetch refspec or \f(CW$fetch\fR if provideed, and add
it to the repository's configuration.
.ie n .SS "create_anonymous( $repo, $url )"
.el .SS "create_anonymous( \f(CW$repo\fP, \f(CW$url\fP )"
.IX Subsection "create_anonymous( $repo, $url )"
Create a remote in memory (anonymous).
.ie n .SS "load( $repo, $name )"
.el .SS "load( \f(CW$repo\fP, \f(CW$name\fP )"
.IX Subsection "load( $repo, $name )"
Load an existing remote. Returns a Git::Raw::Remote object if the remote
was found, otherwise \f(CW\*(C`undef\*(C'\fR.
.ie n .SS "delete( $repo, $name )"
.el .SS "delete( \f(CW$repo\fP, \f(CW$name\fP )"
.IX Subsection "delete( $repo, $name )"
Delete an existing remote.
.SS "owner( )"
.IX Subsection "owner( )"
Retrieve the Git::Raw::Repository owning the remote.
.SS "default_branch( )"
.IX Subsection "default_branch( )"
Retrieve the default branch of remote repository, that is, the branch which
\&\s-1HEAD\s0 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 \f(CW\*(C`undef\*(C'\fR. \fBNote\fR, this function should only be called after
the remote has established a connection.
.SS "name( )"
.IX Subsection "name( )"
Retrieve the name of the remote.
.ie n .SS "rename( $repo, $old_name, $new_name, [ \e@problems ] )"
.el .SS "rename( \f(CW$repo\fP, \f(CW$old_name\fP, \f(CW$new_name\fP, [ \e@problems ] )"
.IX Subsection "rename( $repo, $old_name, $new_name, [ @problems ] )"
Rename a remote. Non-default refspecs cannot be renamed and will be store in
\&\f(CW@problems\fR if provided.
.ie n .SS "url( [ $url ] )"
.el .SS "url( [ \f(CW$url\fP ] )"
.IX Subsection "url( [ $url ] )"
Retrieve the \s-1URL\s0 of the remote. If \f(CW$url\fR is passed, the remote's \s-1URL\s0 will be
updated and returned.
.ie n .SS "pushurl( [ $url ] )"
.el .SS "pushurl( [ \f(CW$url\fP ] )"
.IX Subsection "pushurl( [ $url ] )"
Retrieve the push \s-1URL\s0 for the remote. If \f(CW$url\fR is passed, the remote's push
\&\s-1URL\s0 will be updated and returned.
.ie n .SS "add_fetch( $spec )"
.el .SS "add_fetch( \f(CW$spec\fP )"
.IX Subsection "add_fetch( $spec )"
Add a fetch spec to the remote.
.ie n .SS "add_push( $spec )"
.el .SS "add_push( \f(CW$spec\fP )"
.IX Subsection "add_push( $spec )"
Add a push spec to the remote.
.SS "refspec_count( )"
.IX Subsection "refspec_count( )"
Retrieve the refspec count.
.SS "refspecs( )"
.IX Subsection "refspecs( )"
Retrieve the remote's refspecs. Returns a list of Git::Raw::RefSpec objects.
.SS "ls( )"
.IX Subsection "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:
.IP "\(bu" 4
\&\*(L"local\*(R"
.Sp
Whether the reference exists locally.
.IP "\(bu" 4
\&\*(L"id\*(R"
.Sp
The \s-1OID\s0 of the reference.
.IP "\(bu" 4
\&\*(L"lid\*(R"
.Sp
The local \s-1OID\s0 of the reference (optional).
.SS "fetch( [ \e%fetch_opts ] )"
.IX Subsection "fetch( [ %fetch_opts ] )"
Download new data and update tips. Convenience function to connect to a remote,
download the data, disconnect and update the remote-tracking branches. Valid fields for
the \f(CW%fetch_opts\fR hash are:
.IP "\(bu" 4
\&\*(L"callbacks\*(R"
.Sp
See \f(CW\*(C`CALLBACKS\*(C'\fR.
.IP "\(bu" 4
\&\*(L"prune\*(R"
.Sp
\&\s-1NOT IMPLEMENTED.\s0
.IP "\(bu" 4
\&\*(L"update_fetchead\*(R"
.Sp
\&\s-1NOT IMPLEMENTED.\s0
.IP "\(bu" 4
\&\*(L"download_tags\*(R"
.Sp
\&\s-1NOT IMPLEMENTED.\s0
.IP "\(bu" 4
\&\*(L"custom_headers\*(R"
.Sp
\&\s-1NOT IMPLEMENTED.\s0
.SS "push( \e@refspecs, [ \e%push_opts ] )"
.IX Subsection "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 \f(CW%push_opts\fR hash are:
.IP "\(bu" 4
\&\*(L"callbacks\*(R"
.Sp
See \f(CW\*(C`CALLBACKS\*(C'\fR.
.IP "\(bu" 4
\&\*(L"custom_headers\*(R"
.Sp
\&\s-1NOT IMPLEMENTED.\s0
.ie n .SS "connect( $direction, [ \e%callbacks ] )"
.el .SS "connect( \f(CW$direction\fP, [ \e%callbacks ] )"
.IX Subsection "connect( $direction, [ %callbacks ] )"
Connect to the remote. The \f(CW$direction\fR should either be \f(CW"fetch"\fR or \f(CW"push"\fR.
.SS "disconnect( )"
.IX Subsection "disconnect( )"
Disconnect the remote.
.SS "download( [ \e%fetch_opts ] )"
.IX Subsection "download( [ %fetch_opts ] )"
Download the remote packfile. See \f(CW\*(C`Git::Raw::Remote\->fetch()\*(C'\fR for valid
\&\f(CW%fetch_opts\fR values.
.SS "upload( \e@refspecs, [ \e%push_opts ] )"
.IX Subsection "upload( @refspecs, [ %push_opts ] )"
Create a packfile and send it to the server. \f(CW@refspecs\fR is a list of refspecs
to use for the negotiation with the server to determine the missing objects
that need to be uploaded.
.SS "prune( [ \e%callbacks ] )"
.IX Subsection "prune( [ %callbacks ] )"
Prune tracking refs that are no longer present on remote.
.SS "update_tips( [ \e%callbacks ] )"
.IX Subsection "update_tips( [ %callbacks ] )"
Update the tips to the new status.
.SS "is_connected( )"
.IX Subsection "is_connected( )"
Check if the remote is connected.
.SH "CALLBACKS"
.IX Header "CALLBACKS"
.SS "credentials"
.IX Subsection "credentials"
The callback to be called any time authentication is required to connect to the
remote repository. The callback receives a string \f(CW$url\fR containing the \s-1URL\s0 of
the remote, the \f(CW$user\fR extracted from the \s-1URL\s0 and a list of supported
authentication \f(CW$types\fR. The callback should return either a Git::Raw::Cred
object or alternatively \f(CW\*(C`undef\*(C'\fR to abort the authentication process. \f(CW$types\fR
may contain one or more of the following:
.IP "\(bu" 4
\&\*(L"userpass_plaintext\*(R"
.Sp
Plaintext username and password.
.IP "\(bu" 4
\&\*(L"ssh_key\*(R"
.Sp
A \s-1SSH\s0 key from disk
.IP "\(bu" 4
\&\*(L"ssh_custom\*(R"
.Sp
A \s-1SSH\s0 key with a custom signature function.
.IP "\(bu" 4
\&\*(L"ssh_interactive\*(R"
.Sp
Keyboard-interactive based \s-1SSH\s0 authentication
.IP "\(bu" 4
\&\*(L"username\*(R"
.Sp
Username-only credential information.
.IP "\(bu" 4
\&\*(L"default\*(R"
.Sp
A key for NTLM/Kerberos default credentials.
.PP
\&\fBNote:\fR this callback may be invoked more than once.
.SS "certificate_check"
.IX Subsection "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 \f(CW$valid\fR and \f(CW$host\fR. This callback should return a negative number to
abort.
.SS "sideband_progress"
.IX Subsection "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 \f(CW$msg\fR
containing the progress information.
.SS "transfer_progress"
.IX Subsection "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.
.SS "update_tips"
.IX Subsection "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
\&\f(CW$ref\fR of the reference that was updated, and the two \s-1OID\s0's \f(CW$a\fR before and
after \f(CW$b\fR the update. \f(CW$a\fR will be \f(CW\*(C`undef\*(C'\fR if the reference was created,
likewise \f(CW$b\fR will be \f(CW\*(C`undef\*(C'\fR if the reference was removed.
.SS "push_transfer_progress"
.IX Subsection "push_transfer_progress"
During the upload of new data, this will regularly be called with the transfer
progress. The callback receives the following integers:
\&\f(CW$current\fR, \f(CW$total\fR and \f(CW$bytes\fR.
.SS "push_update_reference"
.IX Subsection "push_update_reference"
For each of the updated references, this will be called with a status report
for the reference. The callback receives \f(CW$ref\fR and \f(CW$msg\fR as strings. If
\&\f(CW$msg\fR is defined, the reference mentioned in \f(CW$ref\fR has not been updated.
.SS "push_negotation"
.IX Subsection "push_negotation"
The callbacks receives a list of updates that will be sent to the destination.
Each items consists of \f(CW$src_refname\fR, \f(CW$dst_refname\fR as well as their OIDs,
\&\f(CW$src\fR and \f(CW$dst\fR. This callback should return a negative number to abort.
.SS "pack_progress"
.IX Subsection "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:
\&\f(CW$stage\fR, \f(CW$current\fR and \f(CW$total\fR.
.SH "AUTHOR"
.IX Header "AUTHOR"
Alessandro Ghedini <alexbio@cpan.org>
.PP
Jacques Germishuys <jacquesg@striata.com>
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
Copyright 2012 Alessandro Ghedini.
.PP
This program is free software; you can redistribute it and/or modify it
under the terms of either: the \s-1GNU\s0 General Public License as published
by the Free Software Foundation; or the Artistic License.
.PP
See http://dev.perl.org/licenses/ for more information.