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_DIR}/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.

gcli 2.2.0                                         2024-Feb-05                                           GCLI(5)