From 0129346eda4cfa964bb146c16b980df5c5c19059 Mon Sep 17 00:00:00 2001
From: Felix Fontein <felix@fontein.de>
Date: Tue, 4 Jun 2024 06:27:50 +0200
Subject: [PATCH] git_config: deprecate reading values (#8453)

Deprecate reading values.
---
 .../8453-git_config-deprecate-read.yml        |  3 ++
 plugins/modules/git_config.py                 | 39 +++++++------------
 2 files changed, 17 insertions(+), 25 deletions(-)
 create mode 100644 changelogs/fragments/8453-git_config-deprecate-read.yml

diff --git a/changelogs/fragments/8453-git_config-deprecate-read.yml b/changelogs/fragments/8453-git_config-deprecate-read.yml
new file mode 100644
index 0000000000..a291568fce
--- /dev/null
+++ b/changelogs/fragments/8453-git_config-deprecate-read.yml
@@ -0,0 +1,3 @@
+deprecated_features:
+  - "git_config - the ``list_all`` option has been deprecated and will be removed in community.general 11.0.0. Use the ``community.general.git_config_info`` module instead (https://github.com/ansible-collections/community.general/pull/8453)."
+  - "git_config - using ``state=present`` without providing ``value`` is deprecated and will be disallowed in community.general 11.0.0. Use the ``community.general.git_config_info`` module instead to read a value (https://github.com/ansible-collections/community.general/pull/8453)."
diff --git a/plugins/modules/git_config.py b/plugins/modules/git_config.py
index a8d2ebe979..2c16821e9e 100644
--- a/plugins/modules/git_config.py
+++ b/plugins/modules/git_config.py
@@ -18,7 +18,7 @@ author:
   - Matthew Gamble (@djmattyg007)
   - Marius Gedminas (@mgedmin)
 requirements: ['git']
-short_description: Read and write git configuration
+short_description: Update git configuration
 description:
   - The M(community.general.git_config) module changes git configuration by invoking C(git config).
     This is needed if you do not want to use M(ansible.builtin.template) for the entire git
@@ -36,6 +36,8 @@ options:
   list_all:
     description:
       - List all settings (optionally limited to a given O(scope)).
+      - This option is B(deprecated) and will be removed from community.general 11.0.0.
+        Please use M(community.general.git_config_info) instead.
     type: bool
     default: false
   name:
@@ -74,6 +76,8 @@ options:
     description:
       - 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, O(value) will be required if O(state=present).
+        To read values, use the M(community.general.git_config_info) module instead.
     type: str
   add_mode:
     description:
@@ -143,29 +147,6 @@ EXAMPLES = '''
     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=true
-  community.general.git_config:
-    name: alias.diffc
-
-- name: Read all values from git config
-  community.general.git_config:
-    list_all: true
-    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: true
-
-- name: Specify a repository to include local settings
-  community.general.git_config:
-    list_all: true
-    repo: /path/to/repo.git
 '''
 
 RETURN = '''
@@ -193,7 +174,7 @@ from ansible.module_utils.basic import AnsibleModule
 def main():
     module = AnsibleModule(
         argument_spec=dict(
-            list_all=dict(required=False, type='bool', default=False),
+            list_all=dict(required=False, type='bool', default=False, removed_in_version='11.0.0', removed_from_collection='community.general'),
             name=dict(type='str'),
             repo=dict(type='path'),
             file=dict(type='path'),
@@ -222,6 +203,14 @@ def main():
     new_value = params['value'] or ''
     add_mode = params['add_mode']
 
+    if not unset and not new_value and not params['list_all']:
+        module.deprecate(
+            'If state=present, a value must be specified from community.general 11.0.0 on.'
+            ' To read a config value, use the community.general.git_config_info module instead.',
+            version='11.0.0',
+            collection_name='community.general',
+        )
+
     scope = determine_scope(params)
     cwd = determine_cwd(scope, params)