Support multiple links in the tmt link command (#3309)

In order to make the syntax consistent with the `tmt test create`
command and to allow providing multiple links in a single command
let's use a ``--link`` option instead of the first argument for
provide the `relation:target` pairs.

docs/guide.rst

@@ -787,7 +787,7 @@ later using the ``tmt link`` command:
 
 .. code-block:: shell
 
-    tmt link verifies:https://issues.redhat.com/browse/YOUR-ISSUE tests/core/smoke
+    tmt link --link verifies:https://issues.redhat.com/browse/YOUR-ISSUE tests/core/smoke
 
 In order to enable this feature, create a configuration file
 ``.config/tmt/link.fmf`` and define an ``issue-tracker`` section

docs/releases.rst

@@ -38,6 +38,10 @@ to override the default locations.
 
 __ https://www.redhat.com/en/technologies/linux-platforms/enterprise-linux/image-mode
 
+The ``tmt link`` command now supports providing multiple links by
+using the ``--link`` option. See the :ref:`link-issues` section
+for example usage.
+
 
 tmt-1.37.0
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

tests/link/basic/main.fmf

@@ -0,0 +1,4 @@
+summary: Check basic functionality of the tmt link command
+description:
+    Make sure that `tmt test create` and `tmt link` add provided
+    target link to the test metadata.

tests/link/basic/test.sh

@@ -0,0 +1,35 @@
+#!/bin/bash
+. /usr/share/beakerlib/beakerlib.sh || exit 1
+
+rlJournalStart
+    rlPhaseStartSetup
+        rlRun "tmp=\$(mktemp -d)" 0 "Create a tmp directory"
+        rlRun "pushd $tmp"
+        rlRun "tmt init"
+    rlPhaseEnd
+
+    rlPhaseStartTest "Create Test"
+        rlRun "tmt test create /test/created --template shell --link verifies:/feature/one"
+        rlRun -s "tmt test show /test/created"
+        rlAssertGrep "verifies /feature/one" $rlRun_LOG
+    rlPhaseEnd
+
+    rlPhaseStartTest "Existing Test"
+        rlRun "tmt test create /test/existing --template shell"
+        rlRun "tmt link /test/existing --link verifies:/feature/two"
+        rlRun "tmt link /test/existing --link verifies:/feature/three"
+        rlRun -s "tmt test show /test/existing"
+        rlAssertGrep "verifies /feature/two" $rlRun_LOG
+        rlAssertGrep "verifies /feature/three" $rlRun_LOG
+    rlPhaseEnd
+
+    rlPhaseStartTest "No Link Provided"
+        rlRun -s "tmt link /test/existing" 2
+        rlAssertGrep "Provide at least one link" $rlRun_LOG
+    rlPhaseEnd
+
+    rlPhaseStartCleanup
+        rlRun "popd"
+        rlRun "rm -r $tmp" 0 "Remove the tmp directory"
+    rlPhaseEnd
+rlJournalEnd

tmt/cli.py

@@ -2242,14 +2242,19 @@ def completion_fish(context: Context, install: bool, **kwargs: Any) -> None:
 
 @main.command(name='link')
 @pass_context
-@click.argument('link', nargs=1, metavar='[RELATION:]TARGET')
 @click.argument('names', nargs=-1, metavar='[TEST|PLAN|STORY]...')
+@option(
+    '--link', 'links', metavar='[RELATION:]TARGET', multiple=True,
+    help="""
+        Issue to which tests, plans or stories should be linked.
+        Can be provided multiple times.
+        """)
 @option(
     '--separate', is_flag=True,
     help="Create linking separately for multiple passed objects.")
 def link(context: Context,
          names: list[str],
-         link: str,
+         links: list[str],
          separate: bool,
          ) -> None:
     """
@@ -2268,8 +2273,12 @@ def link(context: Context,
     if not tmt_objects:
         raise tmt.utils.GeneralError("No test, plan or story found for linking.")
 
-    tmt.utils.jira.link(
-        tmt_objects=tmt_objects,
-        links=tmt.base.Links(data=link),
-        separate=separate,
-        logger=context.obj.logger)
+    if not links:
+        raise tmt.utils.GeneralError("Provide at least one link using the '--link' option.")
+
+    for link in links:
+        tmt.utils.jira.link(
+            tmt_objects=tmt_objects,
+            links=tmt.base.Links(data=link),
+            separate=separate,
+            logger=context.obj.logger)