Configuration

Configuration file location

GrainyHead’s configuration file is looked for, by default, under the path $XDG_CONFIG_HOME/grainyhead/config.

Another location may be specified using the -c or --config option.

If the configuration file (be it the default one or one specified with the -c option) does not exist when grh is called, the conf command will automatically be invoked to prompt the user for enough informations to create a minimal configuration file, as shown in Creating a configuration file.

Once a configuration file has been created, the conf command can be explicitly used again to edit that file with the user’s preferred text editor.

Configuration file syntax

The configuration file’s general syntax is that of .ini files, as supported by Python’s configparser module.

Briefly, the configuration file is organised into sections which start by a bracked-enclosed header and contain key-value pairs.

You can use either a colon (:) or an equal sign (=) to separate keys and values. Leading and trailing whitespaces are ignored, as well as lines starting with either a semi-colon (;) or a number sign (#).

Configuration of repositories

Each section in the configuration file represents a GitHub repository work with.

There must be at least one section, which must be called default. It describes the repository that will be used by default.

To work with more repositories, add more sections to the configuration file, giving each section a unique name. On the command line, select the section (and therefore the repository) to use with the -s or --section option, which expects the name of a configuration section.

Each section must have two keys:

repository

This is the address to the GitHub repository. It can either be a full URL (e.g., https://github.com/gouttegd/grainyhead), or more simply just the name of the GitHub account followed by the name of the repository (e.g., gouttegd/grainyhead).

token

This is the personal access token needed to access the repository through the GitHub API. See GitHub documentation for details on how to obtain such a token.

Note that even if you use a single token to access several repositories (possibly all your repositories), the token must be explicitly specified in each configuration section.

An optional key, caching, can be used to control the file cache. See the Caching section for details on that option.

Sample file

Here is a sample configuration file for GrainyHead:

[default]
repository: https://github.com/gouttegd/grainyhead
token: ghp_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

[bio]
repository: gouttegd/biopython
token: ghp_YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY

With such a file, calling grainyheadh -s bio will make any subcommand work on the Biopython repository. Calling simply grainyhead will make the subcommands work on the GrainyHead repository.