Indicate first-found with ansible-galaxy collection list

Display an asterisk next to the preferred collection when the same FQCN is installed to multiple paths

This will match the collection used by a task, assuming -p is provided to reflect a playbook-adjacent collections path

lib/ansible/cli/galaxy.py

@@ -119,16 +119,18 @@ def with_collection_artifacts_manager(wrapped_method):
     return method_wrapper
 
 
-def _display_header(path, h1, h2, w1=10, w2=7):
-    display.display('\n# {0}\n{1:{cwidth}} {2:{vwidth}}\n{3} {4}\n'.format(
-        path,
-        h1,
-        h2,
-        '-' * max([len(h1), w1]),  # Make sure that the number of dashes is at least the width of the header
-        '-' * max([len(h2), w2]),
-        cwidth=w1,
-        vwidth=w2,
-    ))
+def _display_header(path, h1, h2, w1=10, w2=7, h3=''):
+    optional_column = ' ' if h3 else ''
+    w3 = len(h3)
+
+    # Make sure that the number of dashes is at least the width of the header
+    h1_sep = '-' * max([len(h1), w1])
+    h2_sep = '-' * max([len(h2), w2])
+    h3_sep = '-' * max([len(h3), w3])
+
+    display.display(
+        f"\n# {path}\n{h1:{w1}} {h2:{w2}}{optional_column}{h3}\n{h1_sep} {h2_sep}{optional_column}{h3_sep}\n"
+    )
 
 
 def _display_role(gr):
@@ -141,12 +143,15 @@ def _display_role(gr):
     display.display("- %s, %s" % (gr.name, version))
 
 
-def _display_collection(collection, cwidth=10, vwidth=7, min_cwidth=10, min_vwidth=7):
-    display.display('{fqcn:{cwidth}} {version:{vwidth}}'.format(
+def _display_collection(collection, cwidth=10, vwidth=7, min_cwidth=10, min_vwidth=7, pwidth=0, preferred=False):
+    display.display('{fqcn:{cwidth}} {version:{vwidth}}{optional_column}{preference_marker:{pwidth}}'.format(
         fqcn=to_text(collection.fqcn),
         version=collection.ver,
         cwidth=max(cwidth, min_cwidth),  # Make sure the width isn't smaller than the header
-        vwidth=max(vwidth, min_vwidth)
+        vwidth=max(vwidth, min_vwidth),
+        pwidth=pwidth,
+        optional_column = ' ' if pwidth != 0 else '',
+        preference_marker = '*' if preferred else ''
     ))
 
 
@@ -1638,23 +1643,30 @@ class GalaxyCLI(CLI):
             validate_collection_name(collection_name)
             namespace_filter, collection_filter = collection_name.split('.')
 
-        collections = list(find_existing_collections(
+        collections = []
+        fqcn_precedence = {}
+        for collection in find_existing_collections(
             list(collections_search_paths),
             artifacts_manager,
             namespace_filter=namespace_filter,
             collection_filter=collection_filter,
             dedupe=False
-        ))
+        ):
+            collections.append(collection)
+            fqcn_precedence.setdefault(collection.fqcn, []).append(collection.src)
 
         seen = set()
         fqcn_width, version_width = _get_collection_widths(collections)
+        preferred_header = 'Preferred' if any(len(matches) > 1 for matches in fqcn_precedence.values()) else ''
+
         for collection in sorted(collections, key=lambda c: c.src):
             collection_found = True
             collection_path = pathlib.Path(to_text(collection.src)).parent.parent.as_posix()
+            preferred = preferred_header and fqcn_precedence[collection.fqcn].index(collection.src) == 0
 
             if output_format in {'yaml', 'json'}:
                 collections_in_paths.setdefault(collection_path, {})
-                collections_in_paths[collection_path][collection.fqcn] = {'version': collection.ver}
+                collections_in_paths[collection_path][collection.fqcn] = {'version': collection.ver, 'preferred': preferred}
             else:
                 if collection_path not in seen:
                     _display_header(
@@ -1662,10 +1674,11 @@ class GalaxyCLI(CLI):
                         'Collection',
                         'Version',
                         fqcn_width,
-                        version_width
+                        version_width,
+                        h3=preferred_header,
                     )
                     seen.add(collection_path)
-                _display_collection(collection, fqcn_width, version_width)
+                _display_collection(collection, fqcn_width, version_width, pwidth=len(preferred_header), preferred=preferred)
 
         path_found = False
         for path in collections_search_paths:

lib/ansible/galaxy/collection/__init__.py

@@ -1419,7 +1419,7 @@ def find_existing_collections(path_filter, artifacts_manager, namespace_filter=N
     if path_filter and not is_sequence(path_filter):
         path_filter = [path_filter]
 
-    paths = set()
+    paths = []
     for path in files('ansible_collections').glob('*/*/'):
         path = _normalize_collection_path(path)
         if not path.is_dir():
@@ -1433,7 +1433,7 @@ def find_existing_collections(path_filter, artifacts_manager, namespace_filter=N
                 break
             else:
                 continue
-        paths.add(path)
+        paths.append(path)
 
     seen = set()
     for path in paths:

test/integration/targets/ansible-galaxy-collection/tasks/list.yml

@@ -180,3 +180,36 @@
     that:
       - list_result is failed
       - "'is expected to have a valid SemVer version value but got None' in list_result.stderr"
+
+- name: Initialize the same FQCN in two collection paths
+  command: ansible-galaxy collection init {{ item.fqcn }} --init-path "{{ galaxy_dir }}/{{ item.path }}/ansible_collections" {{ galaxy_verbosity }}
+  loop:
+    - fqcn: common.collection1
+      path: dev
+    - fqcn: common.collection1
+      path: prod
+
+- name: Update version in one of the paths
+  lineinfile:
+    path: "{{ galaxy_dir }}/prod/ansible_collections/common/collection1/galaxy.yml"
+    line: "version: 2.0.0"
+    regexp: "version: .*"
+
+- name: Test listing collection in multiple paths
+  command: ansible-galaxy collection list common.collection1
+  register: list_common_1
+  environment:
+    ANSIBLE_COLLECTIONS_PATH: "{{ galaxy_dir }}/dev:{{ galaxy_dir }}/prod"
+
+- name: Test listing collection in multiple paths with -p
+  command: ansible-galaxy collection list common.collection1 -p {{ galaxy_dir }}/prod
+  register: list_common_2
+  environment:
+    ANSIBLE_COLLECTIONS_PATH: "{{ galaxy_dir }}/dev"
+
+- assert:
+    that:
+      - '"common.collection1 1.0.0   *        " in list_common_1.stdout_lines'
+      - '"common.collection1 2.0.0            " in list_common_1.stdout_lines'
+      - '"common.collection1 1.0.0            " in list_common_2.stdout_lines'
+      - '"common.collection1 2.0.0   *        " in list_common_2.stdout_lines'