Amend CLI globbing help text (7.8.x)

CHANGES.md

@@ -30,6 +30,9 @@ Selected user-facing changes:
 
 ### Enhancements
 
+[#3303](https://github.com/cylc/cylc-flow/pull/3303) - improve CLI
+task-globbing help.
+
 [#3259](https://github.com/cylc/cylc-flow/pull/3259) - sped up suite validation
 (which also affects responsiveness of suite controllers during suite startup,
 restarts, and reloads).  Impact of the speedup is most noticeable when dealing

bin/cylc-documentation

@@ -126,7 +126,7 @@ def main():
         # Suite or task documentation.
         if options.guides or options.www:
             print >> sys.stderr, ("(Note: --guides and --www are ignored for "
-                "suite documentation).")
+                                  "suite documentation).")
         suite = args[0]
         if options.task_name:
             # Task documentation.

bin/cylc-hold

@@ -18,10 +18,11 @@
 
 """cylc [control] hold [OPTIONS] ARGS
 
-Hold one or more waiting tasks (cylc hold REG TASKID ...), or
-a whole suite (cylc hold REG).
+Hold a suite or tasks:
+  cylc hold REG - hold a suite
+  cylc hold REG TASK_GLOB ... - hold one or more tasks in a suite
 
-Held tasks do not submit even if they are ready to run.
+Held tasks do not submit their jobs even if ready to run.
 
 See also 'cylc [control] release'.
 """
@@ -44,7 +45,7 @@ def main():
         __doc__, comms=True, multitask=True,
         argdoc=[
             ("REG", "Suite name"),
-            ('[TASKID ...]', 'Task identifiers')])
+            ('[TASK_GLOB ...]', 'Task match pattern(s)')])
 
     parser.add_option(
         "--after",

bin/cylc-insert

@@ -16,24 +16,21 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-"""cylc [control] insert [OPTIONS] ARGS
+"""cylc [control] insert [OPTIONS] TASK_GLOB [...]
 
-Insert task proxies into a running suite. Uses of insertion include:
- 1) insert a task that was excluded by the suite definition at start-up.
- 2) reinstate a task that was previously removed from a running suite.
- 3) re-run an old task that cannot be retriggered because its task proxy
- is no longer live in the a suite.
+Insert new task proxies into the task pool of a running suite, e.g. to allow
+re-triggering of an earlier task that has already been removed from the pool.
 
-Be aware that inserted cycling tasks keep on cycling as normal, even if
-another instance of the same task exists at a later cycle (instances of
-the same task at different cycles can coexist, but a newly spawned task
-will not be added to the pool if it catches up to another task with the
-same ID).
+NOTE: inserted cycling tasks cycle on as normal, even if another instance of
+the same task exists at a later cycle (instances of the same task at different
+cycles can coexist, but a newly spawned task will not be added to the pool if
+it catches up to another task with the same ID).
 
-See also 'cylc submit', for running tasks without the scheduler.
+See also 'cylc submit', for running tasks independently of the scheduler.
 
-TASK_GLOB is a pattern to match task proxies or task families,
-or groups of them, for a specific cycle point:
+TASK_GLOB matches task or family names, to insert task instances into the pool
+at a specific given cycle point. (NOTE this differs from other commands which
+match name and cycle point patterns against instances already in the pool).
 * CYCLE-POINT/TASK-NAME-GLOB
 * CYCLE-POINT/FAMILY-NAME-GLOB
 * TASK-NAME-GLOB.CYCLE-POINT
@@ -46,8 +43,10 @@ For example, to match, within the given cycle point (e.g. '20200202T0000Z'):
 * all tasks in 'BAR' family: '20200202T0000Z/BAR' or 'BAR.20200202T0000Z'
 * all tasks in 'BAR' or 'BAZ' families: '20200202T0000Z/BA[RZ]' or
   'BA[RZ].20200202T0000Z'
-"""
 
+The old 'MATCH POINT' syntax will be automatically detected and supported. To
+avoid this, use the '--no-multitask-compat' option, or use the new syntax
+(with a '/' or a '.') when specifying 2 TASK_GLOB arguments."""
 
 import sys
 if '--use-ssh' in sys.argv[1:]:
@@ -68,7 +67,7 @@ def main():
         __doc__, comms=True,
         argdoc=[
             ("REG", "Suite name"),
-            ('TASKID [...]', 'Task identifier')])
+            ('TASK_GLOB [...]', 'Task match pattern(s)')])
 
     parser.add_option(
         "--stop-point", "--remove-point",
@@ -78,12 +77,15 @@ def main():
         "--no-check", help="Add task even if the provided cycle point is not "
         "valid for the given task.", action="store_true", default=False)
 
+    parser.add_std_option(
+        "--no-multitask-compat",
+        help="Disallow backward compatible multitask interface.",
+        action="store_false", default=True,
+        dest="multitask_compat")
+
     options, args = parser.parse_args()
     suite = args.pop(0)
 
-    # See "cop.parse_multitask_compat" for back compat discussion
-    # "cop.parse_multitask_compat" cannot be used here because argument 3
-    # (after suite argument) used to be "options.stop_point_string".
     if (options.multitask_compat and len(args) in [2, 3] and
             all("/" not in arg for arg in args) and
             all("." not in arg for arg in args[1:])):

bin/cylc-kill

@@ -19,9 +19,8 @@
 """cylc [control] kill [OPTIONS] ARGS
 
 Kill jobs of active tasks and update their statuses accordingly.
-
-To kill one or more tasks, "cylc kill REG TASKID ..."; to kill all active
-tasks: "cylc kill REG".
+ cylc kill REG TASK_GLOB ... - kill one or more active tasks
+ cylc kill REG - kill all active tasks in the suite
 """
 
 import sys
@@ -43,7 +42,7 @@ def main():
         __doc__, comms=True, multitask=True,
         argdoc=[
             ('REG', 'Suite name'),
-            ('[TASKID ...]', 'Task identifiers')])
+            ('[TASK_GLOB ...]', 'Task match pattern(s)')])
 
     options, args = parser.parse_args()
 

bin/cylc-poll

@@ -19,9 +19,8 @@
 """cylc [control] poll [OPTIONS] ARGS
 
 Poll (query) task jobs to verify and update their statuses.
-
-Use "cylc poll REG" to poll all active tasks, or "cylc poll REG TASKID" to poll
-individual tasks or families, or groups of them.
+  cylc poll REG - poll all active tasks
+  cylc poll REG TASK_GLOB ... - poll multiple active tasks or families
 """
 
 import sys
@@ -42,7 +41,7 @@ def main():
         __doc__, comms=True, multitask=True,
         argdoc=[
             ('REG', 'Suite name'),
-            ('[TASKID ...]', 'Task identifiers')])
+            ('[TASK_GLOB ...]', 'Task match pattern(s)')])
 
     parser.add_option(
         "-s", "--succeeded", help="Allow polling of succeeded tasks.",

bin/cylc-release

@@ -18,9 +18,11 @@
 
 """cylc [control] release|unhold [OPTIONS] ARGS
 
-Release one or more held tasks (cylc release REG TASKID)
-or the whole suite (cylc release REG). Held tasks do not
-submit even if they are ready to run.
+Release a held suite or tasks.
+  cylc release REG - release the suite
+  cylc release REG TASK_GLOB ... - release one or more tasks
+
+Held tasks do not submit their jobs even if ready to run.
 
 See also 'cylc [control] hold'.
 """
@@ -43,7 +45,7 @@ def main():
         __doc__, comms=True, multitask=True,
         argdoc=[
             ("REG", 'Suite name'),
-            ('[TASKID ...]', 'Task identifiers')])
+            ('[TASK_GLOB ...]', 'Task match pattern(s)')])
 
     options, args = parser.parse_args()
     suite = args.pop(0)

bin/cylc-remove

@@ -18,10 +18,10 @@
 
 """cylc [control] remove [OPTIONS] ARGS
 
-Remove one or more tasks (cylc remove REG TASKID), or all tasks with a
-given cycle point (cylc remove REG *.POINT) from a running suite.
+Remove one or more task instances from a running suite.
 
-Tasks will spawn successors first if they have not done so already.
+Tasks will be forced to spawn successors before removal if they have not done
+so already, unless you use '--no-spawn'.
 """
 
 import sys
@@ -42,7 +42,7 @@ def main():
         __doc__, comms=True, multitask=True,
         argdoc=[
             ("REG", "Suite name"),
-            ('TASKID [...]', 'Task identifiers')])
+            ('TASK_GLOB [...]', 'Task match pattern(s)')])
 
     parser.add_option(
         "--no-spawn",

bin/cylc-reset

@@ -18,18 +18,17 @@
 
 """cylc [control] reset [OPTIONS] ARGS
 
-Force tasks to a specified state, and modify their prerequisites and outputs
-accordingly.
+Force task instances to a specified state.
+  cylc reset --state=xxx REG - reset all tasks to state xxx
+  cylc reset --state=xxx REG TASK_GLOB ... - reset one or more tasks to xxx
 
 Outputs are automatically updated to reflect the new task state, except for
-custom message outputs - which can be manipulated directly with "--output".
+custom message outputs which can be manipulated directly with "--output".
 
-Prerequisites reflect the state of other  tasks; they are not changed except
-to unset them on resetting the task state to 'waiting' or earlier.
-
-To hold and release tasks use "cylc hold" and "cylc release".
-"cylc reset --state=spawn" is deprecated: use "cylc spawn" instead.
+Prerequisites reflect the state of other tasks; they are not changed except
+to unset them on resetting state to 'waiting' or earlier.
 
+To hold and release tasks use "cylc hold" and "cylc release", not this command.
 """
 
 import os
@@ -52,7 +51,7 @@ def main():
         __doc__, comms=True, multitask=True,
         argdoc=[
             ('REG', 'Suite name'),
-            ('[TASKID ...]', 'Task identifiers')])
+            ('[TASK_GLOB ...]', 'Task match pattern(s)')])
 
     parser.add_option(
         "-s", "--state", metavar="STATE",

bin/cylc-show

@@ -18,9 +18,11 @@
 
 """cylc [info] show [OPTIONS] ARGS
 
-Interrogate a suite server program for the suite metadata; or for the metadata
-of one of its tasks; or for the current state of the prerequisites, outputs,
-and clock-triggering of a specific task instance."""
+Query a running suite for:
+  cylc show REG - suite metadata
+  cylc show REG TASK_NAME - task metadata
+  cylc show REG TASK_GLOB - prerequisites and outputs of matched task instances
+"""
 
 import sys
 if '--use-ssh' in sys.argv[1:]:
@@ -43,7 +45,7 @@ def main():
         __doc__, comms=True, noforce=True, multitask=True,
         argdoc=[
             ('REG', 'Suite name'),
-            ('[TASKID ...]', 'Task names or identifiers')])
+            ('[TASK_NAME or TASK_GLOB ...]', 'Task names or match patterns')])
 
     parser.add_option('--list-prereqs', action="store_true", default=False,
                       help="Print a task's pre-requisites as a list.")

bin/cylc-shutdown

@@ -15,4 +15,3 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 exec "$(dirname "$0")/cylc-stop" "$@"
-

bin/cylc-spawn

@@ -18,9 +18,13 @@
 
 """cylc [control] spawn [OPTIONS] ARGS
 
-Force one or more task proxies to spawn successors at the next cycle point
-in their sequences.  This is useful if you need to run successive instances
-of a task out of order.
+Force task proxies to spawn successors at their own next cycle point.
+  cylc spawn REG - force spawn all tasks in a suite
+  cylc spawn REG TASK_GLOB ... - force spawn one or more tasks in a suite
+
+Tasks normally spawn on reaching the "submitted" status. Spawning them early
+allows running successive instances of the same task out of order. See also
+the "spawn to max active cycle points" suite configuration.
 """
 
 import sys
@@ -41,7 +45,7 @@ def main():
         __doc__, comms=True, multitask=True,
         argdoc=[
             ('REG', 'Suite name'),
-            ('[TASKID ...]', 'Task identifiers')])
+            ('[TASK_GLOB ...]', 'Task match pattern(s)')])
 
     options, args = parser.parse_args()
 

bin/cylc-trigger

@@ -18,10 +18,14 @@
 
 """cylc [control] trigger [OPTIONS] ARGS
 
-Manually trigger one or more tasks. Waiting tasks will be queued (cylc internal
-queues) and will submit as normal when released by the queue; queued tasks will
-submit immediately even if that violates the queue limit (so you may need to
-trigger a queue-limited task twice to get it to submit).
+Manually trigger tasks.
+  cylc trigger REG - trigger all tasks in a running suite
+  cylc trigger REG TASK_GLOB ... - trigger one or more tasks in a running suite
+
+NOTE waiting tasks that are queue-limited will be queued if triggered, to
+submit as normal when released by the queue; queued tasks will submit
+immediately if triggered, even if that violates the queue limit (so you may
+need to trigger a queue-limited task twice to get it to submit immediately).
 
 For single tasks you can use "--edit" to edit the generated job script before
 it submits, to apply one-off changes. A diff between the original and edited
@@ -62,7 +66,7 @@ def main():
         __doc__, comms=True, multitask=True,
         argdoc=[
             ('REG', 'Suite name'),
-            ('[TASKID ...]', 'Task identifiers')])
+            ('[TASK_GLOB ...]', 'Task match pattern(s)')])
 
     parser.add_option(
         "-e", "--edit",

bin/cylc-view

@@ -127,7 +127,8 @@ def main():
                'empy': options.empy or options.process,
                'jinja2': options.jinja2 or options.process,
                'contin': options.cat or options.process,
-               'inline': options.inline or options.jinja2 or options.empy or options.process,
+               'inline': (options.inline or options.jinja2 or
+                          options.empy or options.process),
                }
     lines = read_and_proc(
         suiterc,

lib/cylc/option_parsers.py

@@ -32,7 +32,11 @@ class CylcOptionParser(OptionParser):
     """Common options for all cylc CLI commands."""
 
     MULTITASK_USAGE = """
-TASKID is a pattern to match task proxies or task families, or groups of them:
+Multiple TASK_GLOBs can be given. They each match task proxy instances in the
+current task pool by task or family name pattern, cycle point pattern, and task
+state. They do NOT match any task at any point in the abstract suite graph; if
+target task instances do not exist in the current pool you must insert them
+first with the "cylc insert" command.
 * [CYCLE-POINT-GLOB/]TASK-NAME-GLOB[:TASK-STATE]
 * [CYCLE-POINT-GLOB/]FAMILY-NAME-GLOB[:TASK-STATE]
 * TASK-NAME-GLOB[.CYCLE-POINT-GLOB][:TASK-STATE]
@@ -49,7 +53,7 @@ class CylcOptionParser(OptionParser):
 
 The old 'MATCH POINT' syntax will be automatically detected and supported. To
 avoid this, use the '--no-multitask-compat' option, or use the new syntax
-(with a '/' or a '.') when specifying 2 TASKID arguments."""
+(with a '/' or a '.') when specifying 2 TASK_GLOB arguments."""
 
     def __init__(self, usage, argdoc=None, comms=False, noforce=False,
                  jset=False, multitask=False, prep=False, auto_add=True,
@@ -235,7 +239,7 @@ def add_std_options(self):
                 help=(
                     "(Obsolete) This option is now ignored "
                     "and is retained for backward compatibility only. "
-                    "TASKID in the argument list can be used to match "
+                    "TASK_GLOB in the argument list can be used to match "
                     "task and family names regardless of this option."),
                 action="store_true", default=False, dest="is_family")
 

tests/cylc-insert/08-insert-family-compat/suite.rc

@@ -27,7 +27,7 @@ cylc remove --no-spawn "$CYLC_SUITE_NAME" "FAM-?.$CYLC_TASK_CYCLE_POINT"
     [[inserter]]
         # Re-insert one family.
         script = """
-cylc insert -m $CYLC_SUITE_NAME FAM-A $CYLC_TASK_CYCLE_POINT
+cylc insert $CYLC_SUITE_NAME FAM-A $CYLC_TASK_CYCLE_POINT
 """
     [[FAM-A, FAM-B]]
     [[a1, a2]]