add a 'min' type for gather_subset to collect nothing (#27085)

previously gather_subset=['!all'] would still gather the
min set of facts, and there was no way to collect no facts.

The 'min' specifier in gather_subset is equilivent to
exclude the minimal_gather_subset facts as well.

   gather_subset=['!all', '!min'] will collect no facts

This also lets explicitly added gather_subsets override excludes.

   gather_subset=['pkg_mgr', '!all', '!min'] will collect only the pkg_mgr
fact.

lib/ansible/module_utils/facts/collector.py

@@ -111,16 +111,31 @@ def get_collector_names(valid_subsets=None,
     additional_subsets = set()
     exclude_subsets = set()
 
-    for subset in gather_subset:
-        subset_id = subset
+    # total always starts with the min set, then
+    # adds of the additions in gather_subset, then
+    # excludes all of the excludes, then add any explicitly
+    # requested subsets.
+    gather_subset_with_min = ['min']
+    gather_subset_with_min.extend(gather_subset)
 
+    # subsets we mention in gather_subset explicitly, except for 'all'/'min'
+    explicitly_added = set()
+
+    for subset in gather_subset_with_min:
+        subset_id = subset
+        if subset_id == 'min':
+            additional_subsets.update(minimal_gather_subset)
+            continue
         if subset_id == 'all':
             additional_subsets.update(valid_subsets)
             continue
         if subset_id.startswith('!'):
             subset = subset[1:]
+            if subset == 'min':
+                exclude_subsets.update(minimal_gather_subset)
+                continue
             if subset == 'all':
-                exclude_subsets.update(valid_subsets)
+                exclude_subsets.update(valid_subsets - minimal_gather_subset)
                 continue
             exclude = True
         else:
@@ -137,14 +152,13 @@ def get_collector_names(valid_subsets=None,
                 raise TypeError("Bad subset '%s' given to Ansible. gather_subset options allowed: all, %s" %
                                 (subset, ", ".join(sorted(valid_subsets))))
 
+            explicitly_added.add(subset)
             additional_subsets.add(subset)
 
     if not additional_subsets:
         additional_subsets.update(valid_subsets)
 
-    additional_subsets.difference_update(exclude_subsets)
-
-    additional_subsets.update(minimal_gather_subset)
+    additional_subsets.difference_update(exclude_subsets - explicitly_added)
 
     return additional_subsets
 

lib/ansible/modules/system/setup.py

@@ -23,13 +23,16 @@ options:
         version_added: "2.1"
         description:
             - "if supplied, restrict the additional facts collected to the given subset.
-              Possible values: all, hardware, network, virtual, ohai, and
+              Possible values: all, min, hardware, network, virtual, ohai, and
               facter Can specify a list of values to specify a larger subset.
               Values can also be used with an initial C(!) to specify that
               that specific subset should not be collected.  For instance:
-              !hardware, !network, !virtual, !ohai, !facter.  Note that a few
-              facts are always collected.  Use the filter parameter if you do
-              not want to display those."
+              !hardware, !network, !virtual, !ohai, !facter. If !all is specified
+              then only the min subset is collected. To avoid collecting even the
+              min subset, specify !all and !min subsets. To collect only specific facts,
+              use !all, !min, and specify the particular fact subsets.
+              Use the filter parameter if you do not want to display some collected
+              facts."
         required: false
         default: 'all'
     gather_timeout:
@@ -93,18 +96,27 @@ EXAMPLES = """
 # Display only facts returned by facter.
 # ansible all -m setup -a 'filter=facter_*'
 
+# Collect only facts returned by facter.
+# ansible all -m setup -a 'gather_subset=!all,!any,facter'
+
 # Display only facts about certain interfaces.
 # ansible all -m setup -a 'filter=ansible_eth[0-2]'
 
-# Restrict additional gathered facts to network and virtual.
+# Restrict additional gathered facts to network and virtual (includes default minimum facts)
 # ansible all -m setup -a 'gather_subset=network,virtual'
 
+# Collect only network and virtual (excludes default minimum facts)
+# ansible all -m setup -a 'gather_subset=!all,!any,network,virtual'
+
 # Do not call puppet facter or ohai even if present.
 # ansible all -m setup -a 'gather_subset=!facter,!ohai'
 
-# Only collect the minimum amount of facts:
+# Only collect the default minimum amount of facts:
 # ansible all -m setup -a 'gather_subset=!all'
 
+# Collect no facts, even the default minimum subset of facts:
+# ansible all -m setup -a 'gather_subset=!all,!min'
+
 # Display facts from Windows hosts with custom facts stored in C(C:\\custom_facts).
 # ansible windows -m setup -a "fact_path='c:\\custom_facts'"
 """