git_config – Read and write git configuration

New in version 2.1.

Synopsis

  • The git_config module changes git configuration by invoking ‘git config’. This is needed if you don’t want to use template for the entire git config file (e.g. because you need to change just user.email in /etc/.git/config). Solutions involving command are cumbersome or don’t work correctly in check mode.

Requirements

The below requirements are needed on the host that executes this module.

  • git

Parameters

Parameter Choices/Defaults Comments
list_all
boolean
    Choices:
  • no ←
  • yes
List all settings (optionally limited to a given scope)
name
-
The name of the setting. If no value is supplied, the value will be read from the config if it has been set.
repo
-
Path to a git repository for reading and writing values from a specific repo.
scope
-
    Choices:
  • local
  • global
  • system
Specify which scope to read/set values from. This is required when setting config values. If this is set to local, you must also specify the repo parameter. It defaults to system only when not using list_all=yes.
state
-
added in 2.8
    Choices:
  • present ←
  • absent
Indicates the setting should be set/unset. This parameter has higher precedence than value parameter: when state=absent and value is defined, value is discarded.
value
-
When specifying the name of a single setting, supply a value to set that setting to the given value.

Examples

# Set some settings in ~/.gitconfig
- git_config:
    name: alias.ci
    scope: global
    value: commit

- git_config:
    name: alias.st
    scope: global
    value: status

# Unset some settings in ~/.gitconfig
- git_config:
    name: alias.ci
    scope: global
    state: absent

# Or system-wide:
- git_config:
    name: alias.remotev
    scope: system
    value: remote -v

- git_config:
    name: core.editor
    scope: global
    value: vim

# scope=system is the default
- git_config:
    name: alias.diffc
    value: diff --cached

- git_config:
    name: color.ui
    value: auto

# Make etckeeper not complain when invoked by cron
- git_config:
    name: user.email
    repo: /etc
    scope: local
    value: 'root@{{ ansible_fqdn }}'

# Read individual values from git config
- git_config:
    name: alias.ci
    scope: global

# scope: system is also assumed when reading values, unless list_all=yes
- git_config:
    name: alias.diffc

# Read all values from git config
- git_config:
    list_all: yes
    scope: global

# When list_all=yes and no scope is specified, you get configuration from all scopes
- git_config:
    list_all: yes

# Specify a repository to include local settings
- git_config:
    list_all: yes
    repo: /path/to/repo.git

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key Returned Description
config_value
string
 success
When list_all=no and value is not set, a string containing the value of the setting in name

Sample:
vim
config_values
dictionary
 success
When list_all=yes, a dict containing key/value pairs of multiple configuration settings

Sample:
{'core.editor': 'vim', 'color.ui': 'auto', 'alias.diffc': 'diff --cached', 'alias.remotev': 'remote -v'}


Status

Authors

  • Matthew Gamble (@djmattyg007)

  • Marius Gedminas (@mgedmin)

Hint

If you notice any issues in this documentation you can edit this document to improve it.