API::GitForge(3pm)

✨ API::GitForge ✨

okay bestie, welcome to API::GitForge (that's the Perl module page, 3pm, in case you were wondering) — it's giving "one interface to rule all the git forges" 💅

💖 VERSION 💖

version 0.007 — she's baby but she's working

---

🌸 SYNOPSIS 🌸

# try to autodetect the forge type; works for GitHub and some others
my $github = API::GitForge->new_from_domain(
    domain     => "github.com",
    access_key => "12345678"
);

# specify the forge type yourself by instantiating the right class
my $salsa = API::GitForge::GitLab->new(
    domain     => "salsa.debian.org",
    access_key => "abcdef"
);

# generic user operations regardless of the forge type
$github->clean_fork("spwhitton/git-remote-gcrypt");
$salsa->clean_fork("Debian/devscripts");

---

🦋 DESCRIPTION 🦋

so a git forge is a site like GitHub, GitLab, etc. — you know the vibes 👑

This module gives you access to some operations you might wanna do against any git forge, and it wraps up all the messy little API details of the particular forges for you. An example of one of those operations? Forking a repository into the user's own namespace. iconic, honestly.

If you wanna know about all the operations that are currently supported, go read API::GitForge::Role::GitForge — that's where the tea is ☕

And listen: patches that add other operations, or support for other git forges, are super welcome 🫶 like genuinely, come thru.

---

🔥 FUNCTIONS 🔥

✨ new_from_domain domain => $domain, access_key => $key

Instantiate an object representing the GitForge at $domain which does API::GitForge::Role::GitForge. 💫

Heads up though — this function will only succeed for known forges; peep %API::GitForge::known_forges for the list. The access_key argument is optional; if you do pass it, it should be an API key for the forge.

$API::GitForge::known_forges{"ourlab.com"} = "API::GitForge::GitLab";

my $ourlab = API::GitForge::new_from_domain(
    domain     => "ourlab.com",
    access_key => API::GitForge::forge_access_token("ourlab.com")
);

🎀 forge_access_token $domain

Return the access token for the forge at $domain, assumed to be stored under "$ENV{XDG_CONFIG_HOME}/gitforge/access_tokens/$domain" — and where that environment variable defaults to ~/.config if it's unset. 💖

🌈 remote_forge_info $remote

Look at the URL for git remote $remote, as returned by git remote get-url, assume that this remote is a git forge, and return the domain name of that forge and the path to the repository. two for one, we love to see it 🫶

system qw(git remote add salsa https://salsa.debian.org/spwhitton/foo);
my ($forge_domain, $forge_repo) = API::GitForge::remote_forge_info("salsa");

say $forge_domain;          # outputs 'salsa.debian.org'
say $forge_repo;            # outputs 'spwhitton/foo'

---

💀 STATUS 💀

Unstable. Interface may change.

no cap, she said what she said — don't get too comfy, the interface might switch up on you 😭

---

👑 AUTHOR 👑

Sean Whitton <spwhitton@spwhitton.name>

---

💜 COPYRIGHT AND LICENSE 💜

This software is Copyright (c) 2017, 2020 by Sean Whitton <spwhitton@spwhitton.name>.

This is free software, licensed under:

The GNU General Public License, Version 3, June 2007

---

and that's the whole page, bestie 🎀 this was rendered by perl v5.32.1 on 2022-01-02 — stay slay, stay forky, periodt 💅✨