Configuration files

class pygit2.Repository(path: str | bytes | None | Path = None, flags: RepositoryOpenFlag = <RepositoryOpenFlag.DEFAULT: 0>)

property config: Config

The configuration file for this repository.

If the configuration hasn’t been set yet, the default config for repository will be returned, including global and system configurations (if they are available).

The Config type

class pygit2.Config(path: PathLike | str | None = None)

Git configuration management.

This class is for the reading and writing of Git configuration files. Configuration files are read individually, either by passing a path into the constructor or by using one of the static methods Config.get_system_config(), Config.get_global_config(), or Config.get_xdg_config(). Additional files can be loaded into the Config object using Config.add_file().

Changes made to the configuration with Config.set_multivar() are immediately persisted to disk. Reads performed with accessor methods like Config.get_multivar() or Config.__getitem__() may result in reading from different versions of the configuration file if this or another process has modified the file. To avoid this and have all read operations occur against the same version of the configuration file, use Config.snapshot() to create a snapshot of the current config. This is especially important when iterating, as the contents of the config might change mid-iteration if you don’t use a snapshot.

This class can technically be used to manually read and write a repository’s configuration file by pointing the constructor to the repository’s .git/config file, but this is not recommended. The resulting Config object represents only the configuration directly within .git/config. It does not represent the total effective configuration for that repository that includes the combined system, global (user), and global (user) XDG. Instead, use BaseRepository.config() for loading a repository’s configuration.

__contains__(key: str | bytes) → bool

__delitem__(key: str | bytes) → None

__getitem__(key: str | bytes) → str | None: When using the mapping interface, the value is returned as a string. In order to apply the git-config parsing rules, you can use Config.get_bool() or Config.get_int().

__iter__() → Iterator[ConfigEntry]: Iterate over configuration entries, returning a ConfigEntry objects. These contain the name, level, and value of each configuration variable. Be aware that this may return multiple versions of each entry if they are set multiple times in the configuration files.

__setitem__(key: str | bytes, value: bool | int | str | bytes) → None

add_file(path: str | PathLike, level: int = 0, force: int = 0) → None: Add a config file instance to an existing config.

delete_multivar(name: str | bytes, regex: str | bytes) → None: Delete a multivar ‘’name’’. ‘’regexp’’ is a regular expression to indicate which values to delete. Changes are persisted to the configuration file(s) backing this Config.

classmethod from_c(repo: BaseRepository | None, ptr: GitConfigC) → Config

get_bool(key: str | bytes) → bool

Look up key and parse its value as a boolean as per the git-config rules. Return a boolean value (True or False).

Truthy values are: ‘true’, 1, ‘on’ or ‘yes’. Falsy values are: ‘false’, 0, ‘off’ and ‘no’

static get_global_config() → Config

Return a Config object representing the global configuration file.

The global configuration file is the one found at the standard user config location for Git, which is $HOME/.gitconfig. This will not find the file at the XDG-compatible user config file location (for that, see Config.get_xdg_config()).

get_int(key: bytes | str) → int

Look up key and parse its value as an integer as per the git-config rules. Return an integer.

A value can have a suffix ‘k’, ‘m’ or ‘g’ which stand for ‘kilo’, ‘mega’ and ‘giga’ respectively.

get_multivar(name: str | bytes, regex: str | None = None) → ConfigMultivarIterator

Get each value of a multivar ‘’name’’ as a list of strings.

The optional ‘’regex’’ parameter is expected to be a regular expression to filter the variables we’re interested in.

static get_system_config() → Config

Return a Config object representing the system configuration file.

The system configuration file is the one found at /etc/gitconfig or %PROGRAMFILES%\Git\etc\gitconfig, depending on the operating system.

static get_xdg_config() → Config

Return a Config object representing the XDG-compatible global configuration file.

The XDG-compatible user config file follows the XDG Base Directory Specification. This file is located at $HOME/.config/git/config. This will not find the file at the standard user config location (for that, see Config.get_global_config()).

static parse_bool(text: str) → bool

static parse_int(text: str) → int

set_multivar(name: str | bytes, regex: str | bytes, value: str | bytes) → None: Set a multivar ‘’name’’ to ‘’value’’. ‘’regexp’’ is a regular expression to indicate which values to replace. Changes are persisted to the configuration file(s) backing this Config.

snapshot() → Config

Create a snapshot from this Config object.

This means that looking up multiple values will use the same version of the configuration files.

The ConfigEntry type

class pygit2.config.ConfigEntry

An entry in a configuration object.

property level: int: The entry’s git_config_level_t value.

property name: str: The entry’s name.

property value: str | None: The entry’s value as a string.