Add git_config module (#1945)

* Add git_config module

This module can be used for reading and writing git configuration at all
three scopes (local, global and system). It supports --diff and --check
out of the box.

This module is based off of the following gist:
https://gist.github.com/mgedmin/b38c74e2d25cb4f47908
I tidied it up and added support for the following:
- Reading values on top of writing them
- Reading and writing values at any scope
The original author is credited in the documentation for the module.

* Respond to review feedback

- Improve documentation by adding choices for parameters, requirements
  for module, and add missing description for scope parameter.
- Fail gracefully when git is not installed (followed example of puppet
  module).
- Remove trailing whitespace.

* Change repo parameter to type 'path'

This ensures that all paths are automatically expanded appropriately.

* Set locale to C before running commands to ensure consistent error messages

This is important to ensure error message parsing occurs correctly.

* Adjust comment
This commit is contained in:
Matthew 2016-04-28 04:36:11 +10:00 committed by Brian Coca
parent 95018b5fe8
commit d91baee7c9

219
system/git_config.py Normal file
View file

@ -0,0 +1,219 @@
#!/usr/bin/python
# -*- coding: utf-8 -*-
# (c) 2015, Marius Gedminas <marius@pov.lt>
# (c) 2016, Matthew Gamble <git@matthewgamble.net>
#
# This file is part of Ansible
#
# Ansible is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# Ansible is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with Ansible. If not, see <http://www.gnu.org/licenses/>.
DOCUMENTATION = '''
---
module: git_config
author:
- "Matthew Gamble"
- "Marius Gedminas"
version_added: 2.1
requirements: ['git']
short_description: Read and write git configuration
description:
- The M(git_config) module changes git configuration by invoking 'git config'.
This is needed if you don't want to use M(template) for the entire git
config file (e.g. because you need to change just C(user.email) in
/etc/.git/config). Solutions involving M(command) are cumbersone or
don't work correctly in check mode.
options:
list_all:
description:
- List all settings (optionally limited to a given I(scope))
required: false
choices: [ "yes", "no" ]
default: no
name:
description:
- The name of the setting. If no value is supplied, the value will
be read from the config if it has been set.
required: false
default: null
repo:
description:
- Path to a git repository for reading and writing values from a
specific repo.
required: false
default: null
scope:
description:
- 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 I(list_all)=yes.
required: false
choices: [ "local", "global", "system" ]
default: null
value:
description:
- When specifying the name of a single setting, supply a value to
set that setting to the given value.
required: false
default: null
'''
EXAMPLES = '''
# Set some settings in ~/.gitconfig
- git_config: name=alias.ci scope=global value=commit
- git_config: name=alias.st scope=global value=status
# 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 = '''
---
config_value:
description: When list_all=no and value is not set, a string containing the value of the setting in name
returned: success
type: string
sample: "vim"
config_values:
description: When list_all=yes, a dict containing key/value pairs of multiple configuration settings
returned: success
type: dictionary
sample:
core.editor: "vim"
color.ui: "auto"
alias.diffc: "diff --cached"
alias.remotev: "remote -v"
'''
def main():
module = AnsibleModule(
argument_spec=dict(
list_all=dict(required=False, type='bool', default=False),
name=dict(type='str'),
repo=dict(type='path'),
scope=dict(required=False, type='str', choices=['local', 'global', 'system']),
value=dict(required=False)
),
mutually_exclusive=[['list_all', 'name'], ['list_all', 'value']],
required_if=[('scope', 'local', ['repo'])],
required_one_of=[['list_all', 'name']],
supports_check_mode=True,
)
git_path = module.get_bin_path('git')
if not git_path:
module.fail_json(msg="Could not find git. Please ensure it is installed.")
params = module.params
# We check error message for a pattern, so we need to make sure the messages appear in the form we're expecting.
# Set the locale to C to ensure consistent messages.
module.run_command_environ_update = dict(LANG='C', LC_ALL='C', LC_MESSAGES='C', LC_CTYPE='C')
if params['name']:
name = params['name']
else:
name = None
if params['scope']:
scope = params['scope']
elif params['list_all']:
scope = None
else:
scope = 'system'
if params['value']:
new_value = params['value']
else:
new_value = None
args = [git_path, "config"]
if params['list_all']:
args.append('-l')
if scope:
args.append("--" + scope)
if name:
args.append(name)
if scope == 'local':
dir = params['repo']
elif params['list_all'] and params['repo']:
# Include local settings from a specific repo when listing all available settings
dir = params['repo']
else:
# Run from root directory to avoid accidentally picking up any local config settings
dir = "/"
(rc, out, err) = module.run_command(' '.join(args), cwd=dir)
if params['list_all'] and scope and rc == 128 and 'unable to read config file' in err:
# This just means nothing has been set at the given scope
module.exit_json(changed=False, msg='', config_values={})
elif rc >= 2:
# If the return code is 1, it just means the option hasn't been set yet, which is fine.
module.fail_json(rc=rc, msg=err, cmd=' '.join(args))
if params['list_all']:
values = out.rstrip().splitlines()
config_values = {}
for value in values:
k, v = value.split('=', 1)
config_values[k] = v
module.exit_json(changed=False, msg='', config_values=config_values)
elif not new_value:
module.exit_json(changed=False, msg='', config_value=out.rstrip())
else:
old_value = out.rstrip()
if old_value == new_value:
module.exit_json(changed=False, msg="")
if not module.check_mode:
new_value_quoted = "'" + new_value + "'"
(rc, out, err) = module.run_command(' '.join(args + [new_value_quoted]), cwd=dir)
if err:
module.fail_json(rc=rc, msg=err, cmd=' '.join(args + [new_value_quoted]))
module.exit_json(
msg='setting changed',
diff=dict(
before_header=' '.join(args),
before=old_value + "\n",
after_header=' '.join(args),
after=new_value + "\n"
),
changed=True
)
from ansible.module_utils.basic import *
if __name__ == '__main__':
main()