Originally Ghub supported only Github but now it also supports Gitlab,
Gitea, Gogs and Bitbucket. The function
ghub-request and all the
ghub-METHOD convenience wrappers default to acting on a Github forge
but can be told to act on another forge using their FORGE argument.
The FORGE argument only specifies what kind of forge to act on, not which instance. The HOST argument can be used to select the instance. For some forges a default instance is defined:
githubdefaults to host
gitlabdefaults to host
bitbucketdefaults to host
localhost:3000/api/v1is used as the default host in both cases.
Together the FORGE and HOST arguments specify the forge type and instance. In addition to that, it is also necessary to specify on whose behalf the request is being made, which can be done using the USERNAME and AUTH arguments.
Having to specify these arguments for every request is inconvenient. Additional variables and convenience functions can be used to make that unnecessary in most cases.
These variables can be set globally and/or for a specific repository as explained in Configuration Variables with a focus on Github instances. To summarize:
github.userspecifies the user.
githubinstance the Git variable
github.HOST.userspecifies the user. The HOST in that variable name is the same as the value of the HOST argument of the called function.
github.hostcan be used. This should only be set locally.
bitbucket forges similar variables are available:
gitlab.userspecifies the https://gitlab.com user.
gitlab.HOST.userspecifies the user for the HOST
gitlabhost, unless the HOST argument is non-nil
bitbucket.userspecifies the https://bitbucket.org user.
bitbucket.HOST.userspecifies the user for the HOST
bitbuckethost, unless the HOST argument is non-nil.
gogs forges some similar variables are available,
however for some of the
ghub.* variables no equivalent variable
exist for these two forges:
gitea.useris not used because no canonical
gitea.HOST.userspecifies the user for the HOST
giteahost, unless the HOST argument is non-nil
gogs.useris not used because no canonical
gogs.HOST.userspecifies the user for the HOST
gogshost, unless the HOST argument is non-nil
ghub-METHOD can be used to make a request for any
of the supported forge types, but except when making a request for
github instance, then that requires the use of the FORGE argument.
To avoid that, functions named
FORGE-METHOD are also
available. The following forms are equivalent, for example:
(ghub-get ... :auth 'PACKAGE :forge 'gitlab) (glab-get ... :auth 'PACKAGE)
These forms would remain equivalent even if you did not specify a
value for the AUTH arguments — but you should not do that if you plan
to share your code with others (see Using Ghub in a Package). If you
do omit AUTH, then the request is made on behalf of the
regardless of the symbol prefix of the function you use to do so.
FORGE-METHOD functions, including but not
ghub-METHOD, are very simple wrappers around
They take fewer arguments than
ghub-request and instead pass constant
values for the arguments METHOD and/or FORGE.