community.general.git_config – Read and write git configuration

Note

This plugin is part of the community.general collection (version 3.8.1).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.general.

To use it in a playbook, specify: community.general.git_config.

Synopsis

  • The git_config module changes git configuration by invoking ‘git config’. This is needed if you don’t want to use ansible.builtin.template for the entire git config file (e.g. because you need to change just user.email in /etc/.git/config). Solutions involving ansible.builtin.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
file
path
added in 2.0.0 of community.general
Path to an adhoc git configuration file to be managed using the file scope.
list_all
boolean
    Choices:
  • no
  • yes
List all settings (optionally limited to a given scope).
name
string
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
Path to a git repository for reading and writing values from a specific repo.
scope
string
    Choices:
  • file
  • 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.
If this is set to file, you must also specify the file parameter.
It defaults to system only when not using list_all=yes.
state
string
    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
string
When specifying the name of a single setting, supply a value to set that setting to the given value.

Examples

- name: Add a setting to ~/.gitconfig
  community.general.git_config:
    name: alias.ci
    scope: global
    value: commit

- name: Add a setting to ~/.gitconfig
  community.general.git_config:
    name: alias.st
    scope: global
    value: status

- name: Remove a setting from ~/.gitconfig
  community.general.git_config:
    name: alias.ci
    scope: global
    state: absent

- name: Add a setting to ~/.gitconfig
  community.general.git_config:
    name: core.editor
    scope: global
    value: vim

- name: Add a setting system-wide
  community.general.git_config:
    name: alias.remotev
    scope: system
    value: remote -v

- name: Add a setting to a system scope (default)
  community.general.git_config:
    name: alias.diffc
    value: diff --cached

- name: Add a setting to a system scope (default)
  community.general.git_config:
    name: color.ui
    value: auto

- name: Make etckeeper not complaining when it is invoked by cron
  community.general.git_config:
    name: user.email
    repo: /etc
    scope: local
    value: 'root@{{ ansible_fqdn }}'

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

- name: Scope system is also assumed when reading values, unless list_all=yes
  community.general.git_config:
    name: alias.diffc

- name: Read all values from git config
  community.general.git_config:
    list_all: yes
    scope: global

- name: When list_all is yes and no scope is specified, you get configuration from all scopes
  community.general.git_config:
    list_all: yes

- name: Specify a repository to include local settings
  community.general.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:
{'alias.diffc': 'diff --cached', 'alias.remotev': 'remote -v', 'color.ui': 'auto', 'core.editor': 'vim'}


Authors

  • Matthew Gamble (@djmattyg007)
  • Marius Gedminas (@mgedmin)

© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/community/general/git_config_module.html