community.general.git_config module – Update git configuration

Note

This module is part of the community.general collection (version 10.0.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. You need further requirements to be able to use this module, see Requirements for details.

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

Synopsis

Requirements

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

  • git

Parameters

Parameter

Comments

add_mode

string

added in community.general 8.1.0

Specify if a value should replace the existing value(s) or if the new value should be added alongside other values with the same name.

This option is only relevant when adding/replacing values. If state=absent or values are just read out, this option is not considered.

Choices:

  • "add"

  • "replace-all" ← (default)

file

path

added in community.general 2.0.0

Path to an adhoc git configuration file to be managed using the file scope.

list_all

boolean

List all settings (optionally limited to a given scope).

This option is deprecated and will be removed from community.general 11.0.0. Please use community.general.git_config_info instead.

Choices:

  • false ← (default)

  • true

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

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=true.

Choices:

  • "file"

  • "local"

  • "global"

  • "system"

state

string

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.

Choices:

  • "present" ← (default)

  • "absent"

value

string

When specifying the name of a single setting, supply a value to set that setting to the given value.

From community.general 11.0.0 on, value will be required if state=present. To read values, use the community.general.git_config_info module instead.

Attributes

Attribute

Support

Description

check_mode

Support: full

Can run in check_mode and return changed status prediction without modifying target.

diff_mode

Support: none

Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode.

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: Add several options for the same name
  community.general.git_config:
    name: push.pushoption
    value: "{{ item }}"
    add_mode: add
  loop:
    - merge_request.create
    - merge_request.draft

- 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 }}'

Return Values

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

Key

Description

config_value

string

When list_all=false and value is not set, a string containing the value of the setting in name

Returned: success

Sample: "vim"

config_values

dictionary

When list_all=true, a dict containing key/value pairs of multiple configuration settings

Returned: success

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

Authors

  • Matthew Gamble (@djmattyg007)

  • Marius Gedminas (@mgedmin)