Git::Raw::Remote(3pm)

💖 Git::Raw::Remote 💖

Hi bestie!! So this is the User Contributed Perl Documentation page for Git::Raw::Remote(3pm), and it's literally the class that represents a Git remote. Remote class energy only. No notes. 🫶

Heads up before we even start: ⚠️ The API of this module is unstable and may change without warning (any change will be appropriately documented in the changelog). So like… don't get too attached to anything, okay? It said what it said. 💀

---

🌸 NAME 🌸

Git::Raw::Remote — Git remote class. That's her. That's the whole name. 🎀

⭐ VERSION ⭐

version 0.90 — yes, the girlies are on 0.90. 👑

✨ SYNOPSIS ✨

Okay so here's the demo, and it's giving main character. Look at this:

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;

It's giving "I can talk to a whole other repository and come back with the goods." Periodt. 💅

🦋 DESCRIPTION 🦋

A Git::Raw::Remote represents a Git remote. That's the vibe. That's the whole job. 🌈

🔥 METHODS 🔥

create( $repo, $name, $url, [$fetch] )

Create a remote with the default fetch refspec — or with $fetch if you actually passed one — and add it to the repository's configuration. Building her and filing her paperwork at the same time. ✨

create_anonymous( $repo, $url )

Create a remote in memory (anonymous). No config, no record, no trace. Ninja mode. 🥷

load( $repo, $name )

Load an existing remote. Returns a Git::Raw::Remote object if the remote was found, otherwise undef. (So check for undef, bestie, don't be out here dereferencing nothing. 😭)

delete( $repo, $name )

Delete an existing remote. Gone. Blocked. Unfollowed. 💀

owner( )

Retrieve the Git::Raw::Repository owning the remote. Find out whose remote this actually is. 🕵️

default_branch( )

Retrieve the default branch of the remote repository — so like, the branch that HEAD points to. If the remote doesn't support reporting this info directly, it does the guess the way git does, which is: if there are multiple branches pointing to the same commit, the first one gets chosen. And if master is a candidate, master wins. Iconic favoritism, love that for her. 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. Don't jump the gun. 👀

name( )

Retrieve the name of the remote. Her name. Her whole identity. 🎀

rename( $repo, $old_name, $new_name, [ \@problems ] )

Rename a remote. Non-default refspecs cannot be renamed and will be stored in @problems if you provided it. So if you hand her the array ref, she'll tell you exactly what she couldn't rebrand. 🙈

url( [ $url ] )

Retrieve the URL of the remote. If $url is passed, the remote's URL will be updated and returned. Two birds, one slay. 🐦

pushurl( [ $url ] )

Retrieve the push URL for the remote. If $url is passed, the remote's push URL will be updated and returned. Same energy, but for pushing. 📤

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. Just a number. A little census. 🔢

refspecs( )

Retrieve the remote's refspecs. Returns a list of Git::Raw::RefSpec objects. Collect them all. 🌸

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. This is the convenience function that does the whole routine: connect to a remote, download the data, disconnect, and update the remote-tracking branches. @refspecs is an optional list of refspecs used for the negotiation with the server to figure out which missing objects 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.

Fr fr, those last four are just placeholders sitting there looking pretty. Don't come for me. 🫠

push( \@refspecs, [ \%push_opts ] )

Perform all the steps of a push, including uploading new data and updating the remote tracking-branches. The full send. 📬

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". Pick a lane. 🛣️

disconnect( )

Disconnect the remote. Hang up. Peace out. ✌️

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 used 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. If it's not on the remote anymore, it doesn't get to live in your tracking refs. Cleanup era. 🧹

update_tips( [ \%callbacks ] )

Update the tips to the new status. Fresh tips, new her. ✨

is_connected( )

Check if the remote is connected. A simple yes/no vibe check. 🔌

---

🎀 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. She's persistent. She'll ask again. 😌

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. Live commentary from the server, basically. 🎙️

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. Birth and death of a ref, captured in real time. 😭

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. So a defined $msg is the "it didn't work" signal. 💀

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. ⚠️ Yes, she warned you about the perf. That's real. 🐌

---

👑 AUTHOR 👑

• Alessandro Ghedini <alexbio@cpan.org>
• Jacques Germishuys <jacquesg@cpan.org>

Legends, both of them. Credit where it's due. 🫶

📜 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.

---

And that's the whole page, bestie!! ✨ This was Git::Raw::Remote(3pm) from perl v5.42.3, dated 2026-08-19. Go forth and remote responsibly. 🦋💖 Mwah.