oracular (5) gcli.5.gz

NAME

     gcli — gcli configuration file formats

DESCRIPTION

     gcli has two different configuration files. A user configuration file that contains default values for gcli
     and a repository-local configuration that contains sensible default values for a given repository. The
     latter is meant to be checked into the repository and provide these default values to other users as well.

   User Configuration File
     The user configuration file is located in ${XDG_CONFIG_HOME}/gcli/config.  On most systems this equal to
     ${HOME}/.config/gcli/config.

     The user configuration file contains definitions for accounts as well as sensible default values for things
     like an editor.

     The file is structured in sections, each section has a name and consists of a collection of key-value
     pairs. E.g.:

           section-name {
                   key1 = value 1
                   key2 = value 2
           }

     There must be a section named “defaults” which may contain the following keys:

     editor  Path to a default editor. This might be overridden by the environment variable EDITOR.

     github-default-account
             Section name of a default GitHub account to use whenever the account is unspecified on the command
             line or in the environment. See GCLI_ACCOUNT in gcli(1).

     gitlab-default-account
             Section name of a default GitLab account to use whenever the account is unspecified on the command
             line or in the environment. See GCLI_ACCOUNT in gcli(1).

     gitea-default-account
             Section name of a default Gitea account to use whenever the account is unspecified on the command
             line or in the environment. See GCLI_ACCOUNT in gcli(1).

     All other sections define accounts for forges. Each of these account definitions have the account name as
     their section name and may have one or more of the following keys defined:

     forge-type  The type of the forge. May be one of:
                 •   github
                 •   gitlab
                 •   gitea

     api-base    (optional) Used to override the API base URL of the forge. This is useful for self-hosted
                 instances.  Depending on the “forge-type” the default values are:

                 forge-type    default value
                 github        https://api.github.com
                 gitlab        https://gitlab.com/api/v4
                 gitea         https://codeberg.org/api/v1

     account     (optional) The username used to authenticate at the API.

     token       (optional) A generated application token to use with this account.  TODO: Document for each
                 forge how to generate these.

   Repository Local Configuration File
     For repository-local configuration you can use a special configuration file. It contains definitions for
     gcli that are specific to the repository.

     The Repository-local configuration file is located in the root directory of the repository and should be
     named .gcli.

     It contains a list of key-value pairs. Allowed keys are:

     pr.base      Name of a branch that the changes should be merged into by default.  Usually this is one of
                  master, main or trunk.

     pr.upstream  Name of the upstream repository to submit the pull request to by default.  This is a pair of
                  the format “owner/repository”.

     pr.inhibit-delete-source-branch
                  If defined and set to “yes” this will prevent the pull request source branch to get deleted
                  when merging a pull request by default.

     forge-type   When hosting on multiple forges this can be set to a type that will be used as a default when
                  other overrides are unspecified. For possible values see the equivalent definition in User
                  Configuration File.

EXAMPLES

   User Configuration File
     An example for the user configuration file consisting of both a Github and a Gitlab account:

     defaults {
             editor=/path/to/ganoooo/emacs
             github-default-account=herrhotzenplotz-gh
             gitlab-default-account=herrhotzenplotz-gitlab
     }

     herrhotzenplotz-gh {
             account=herrhotzenplotz
             token=foobar
             apibase=https://api.github.com
             forge-type=github
     }

     herrhotzenplotz-gl {
             account=herrhotzenplotz
             token=<valid gitlab api token>
             apibase=https://gitlab.com/api/v4
             forge-type=gitlab
     }

     Notice that this allows you to run gcli and force it to use a specific Gitlab account. E.g.:

     $ gcli -a herrhotzenplotz-gl issues -a

   Repository-Local Configuration file
     The .gcli file for the gcli project itself looks like this:

     pr.upstream=herrhotzenplotz/gcli
     pr.base=trunk
     pr.inhibit-delete-source-branch=yes

SEE ALSO

     git(1), gcli(1)

AUTHORS

     Nico Sonack aka. herrhotzenplotz <nsonack@herrhotzenplotz.de> and contributors.

BUGS

     Please report bugs via E-Mail to ~herrhotzenplotz/gcli-discuss@lists.sr.ht.

     Alternatively you can report them on any of the forges linked at https://herrhotzenplotz.de/gcli. However,
     the preferred and quickest method is to use the mailing list.