.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" 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 "API::GitForge 3pm"
.TH API::GitForge 3pm "2021-02-09" "perl v5.32.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"
API::GitForge \- generic interface to APIs of sites like GitHub, GitLab etc.
.SH "VERSION"
.IX Header "VERSION"
version 0.006
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 5
\&    # 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");
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
A \fIgit forge\fR is a site like GitHub, GitLab etc.  This module
provides access to some operations which one might wish to perform
against any git forge, wrapping the details of the APIs of particular
forges.  An example of such an operation is forking a repository into
the user's own namespace.
.PP
See API::GitForge::Role::GitForge for details of all the currently
supported operations.  Patches adding other operations, and support
for other git forges, are welcome.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.ie n .SS "new_from_domain domain => $domain, access_key => $key"
.el .SS "new_from_domain domain => \f(CW$domain\fP, access_key => \f(CW$key\fP"
.IX Subsection "new_from_domain domain => $domain, access_key => $key"
Instantiate an object representing the GitForge at \f(CW$domain\fR which
does API::GitForge::Role::GitForge.  This function will only
succeed for known forges; see \f(CW%API::GitForge::known_forges\fR.  The
\&\f(CW\*(C`access_key\*(C'\fR argument is optional; if present, it should be an \s-1API\s0
key for the forge.
.PP
.Vb 1
\&    $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")
\&    );
.Ve
.ie n .SS "forge_access_token $domain"
.el .SS "forge_access_token \f(CW$domain\fP"
.IX Subsection "forge_access_token $domain"
Return access token for forge at \f(CW$domain\fR, assumed to be stored
under \f(CW\*(C`$ENV{XDG_CONFIG_HOME}/gitforge/access_tokens/$domain\*(C'\fR where
the environment variable defaults to \f(CW\*(C`~/.config\*(C'\fR if unset.
.ie n .SS "remote_forge_info $remote"
.el .SS "remote_forge_info \f(CW$remote\fP"
.IX Subsection "remote_forge_info $remote"
Look at the \s-1URL\s0 for git remote \f(CW$remote\fR, as returned by \f(CW\*(C`git remote
get\-url\*(C'\fR, assume that this remote is a git forge, and return the
domain name of that forge and the path to the repository.
.PP
.Vb 2
\&    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 \*(Aqsalsa.debian.org\*(Aq
\&    say $forge_repo;            # outputs \*(Aqspwhitton/foo\*(Aq
.Ve
.SH "STATUS"
.IX Header "STATUS"
Unstable.  Interface may change.
.SH "AUTHOR"
.IX Header "AUTHOR"
Sean Whitton <spwhitton@spwhitton.name>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is Copyright (c) 2017, 2020 by Sean Whitton <spwhitton@spwhitton.name>.
.PP
This is free software, licensed under:
.PP
.Vb 1
\&  The GNU General Public License, Version 3, June 2007
.Ve