Basic Concepts Arguments and Variables (Ghub User and Developer Manual)

2.1 Basic Concepts, Arguments and Variables

Originally Ghub supported only Github but now it also supports Gitlab, Gitea, Gogs and Bitbucket. For the historic reason just given, the function ghub-request defaults to acting on a github forge, but can be told to act on another forge using the 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:

Forge github defaults to host api.github.com.
Forge gitlab defaults to host gitlab.com/api/v4.
Forge bitbucket defaults to host api.bitbucket.org/2.0.
No canonical host exists for the gitea and gogs forges and localhost:3000/api/v1 is 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. For example:

(ghub-request "GET" "/user" nil
              :forge 'github
              :host "api.github.com"
              :username "tarsius"
              :auth 'forge)

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.

(But for debugging purposes the above explicit form is very useful. You will obviously have to change the value of USERNAME and you should use ghub as AUTH when first trying this at home.)

These variables can be set globally and/or for a specific repository.

For "api.github.com" (aka the API of https://github.com) the Git variable github.user specifies the user.
For another github instance the Git variable github.HOST.user specifies the user. The HOST in that variable name is the same as the value of the HOST argument of the called function.
Instead of specifying the HOST in every function call, the Git variable github.host can be used. This should only be set locally.

These github specific variables are discussed in more detail in Github Configuration Variables.

For gitlab and bitbucket forges similar variables are available:

gitlab.user specifies the https://gitlab.com user.
gitlab.HOST.user specifies the user for the HOST gitlab instance.
gitlab.host specifies the gitlab host, unless the HOST argument is non-nil
bitbucket.user specifies the https://bitbucket.org user.
bitbucket.HOST.user specifies the user for the HOST bitbucket instance.
bitbucket.host specifies the bitbucket host, unless the HOST argument is non-nil.

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

gitea.user is not used because no canonical gitea instance exists.
gitea.HOST.user specifies the user for the HOST gitea instance.
gitea.host specifies the gitea host, unless the HOST argument is non-nil
gogs.user is not used because no canonical gitea instance exists.
gogs.HOST.user specifies the user for the HOST gogs instance.
gogs.host specifies the gogs host, unless the HOST argument is non-nil