Next: , Up: Support for Other Forges   [Contents]

7.1 Forge Functions and Variables

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:

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:

For gitlab and bitbucket forges similar variables are available:

For gitea and gogs forges some similar variables are available, however for some of the ghub.* variables no equivalent variable exist for these two forges:

ghub-request and ghub-METHOD can be used to make a request for any of the supported forge types, but except when making a request for a github instance, then that requires the use of the FORGE argument.

To avoid that, functions named FORGE-request and 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 ghub package, regardless of the symbol prefix of the function you use to do so.

All FORGE-request and FORGE-METHOD functions, including but not limited to ghub-METHOD, are very simple wrappers around ghub-request. They take fewer arguments than ghub-request and instead pass constant values for the arguments METHOD and/or FORGE.

Next: , Up: Support for Other Forges   [Contents]