Amend CLI globbing help text.

CHANGES.md

@@ -33,6 +33,9 @@ Jinja filters were moved from its `Jinja2Filters` folder to within the
 
 ### Enhancements
 
+[#3302](https://github.com/cylc/cylc-flow/pull/3302) - improve CLI
+task-globbing help.
+
 [#3096](https://github.com/cylc/cylc-flow/pull/3096) - add colour to the
 Cylc CLI.
 

bin/cylc-hold

@@ -18,10 +18,11 @@
 
 """cylc [control] hold [OPTIONS] ARGS
 
-Hold one or more waiting tasks (cylc hold REG TASK_GLOB ...), or
-a whole suite (cylc hold REG).
+Hold a workflow or tasks:
+  cylc hold REG - hold a workflow
+  cylc hold REG TASK_GLOB ... - hold one or more tasks in a workflow
 
-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'.
 """

bin/cylc-insert

@@ -16,19 +16,15 @@
 # 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
-
-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.
-
-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).
+"""cylc [control] insert [OPTIONS] TASK_GLOB [...]
+
+Insert new task proxies into the task pool of a running workflow, to enable
+(for example) re-triggering earlier tasks already removed from the pool.
+
+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.
 """

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 TASK_GLOB ..."; 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 workflow
 """
 
 import sys

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 TASK_GLOB"
-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

bin/cylc-release

@@ -18,9 +18,10 @@
 
 """cylc [control] release|unhold [OPTIONS] ARGS
 
-Release one or more held tasks (cylc release REG TASK_GLOB)
-or the whole suite (cylc release REG). Held tasks do not
-submit even if they are ready to run.
+Release a held workflow or tasks.
+  cylc release REG - release the workflow
+  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'.
 """

bin/cylc-remove

@@ -18,10 +18,10 @@
 
 """cylc [control] remove [OPTIONS] ARGS
 
-Remove one or more tasks (cylc remove REG TASK_GLOB), 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 workflow.
 
-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

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

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 workflow for:
+  cylc show REG - workflow 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:]:
@@ -44,7 +46,7 @@ def get_option_parser():
         __doc__, comms=True, noforce=True, multitask=True,
         argdoc=[
             ('REG', 'Suite name'),
-            ('[TASKS ...]', 'Task names or ids (name.cycle)')])
+            ('[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-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 workflow
+  cylc spawn REG TASK_GLOB ... - force spawn one or more tasks in a workflow
+
+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" workflow configuration.
 """
 
 import sys

bin/cylc-trigger

@@ -17,10 +17,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 workflow
+  cylc trigger REG TASK_GLOB ... - trigger some tasks in a running workflow
+
+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

cylc/flow/option_parsers.py

@@ -32,18 +32,24 @@ class CylcOptionParser(OptionParser):
     """Common options for all cylc CLI commands."""
 
     # Shared text for commands which can, & cannot, glob on cycle points:
-    MULTI_USAGE_TEMPLATE = """
-TASK_GLOB is a pattern to match task proxies or task families,
-or groups of them{0}:{1}
+    MULTI_USAGE_TEMPLATE = """{0}
 
-For example, to match{2}:{3}"""
+For example, to match:{1}"""
     # Help text either including or excluding globbing on cycle points:
     WITH_CYCLE_GLOBS = """
+One or more TASK_GLOBs can be given to match task instances in the current task
+pool, by task or family name pattern, cycle point pattern, and task state. Note
+this command does not operate on tasks at any arbitrary point in the abstract
+workflow graph - tasks not already in the pool must be inserted first with the
+"cylc insert" command in order to be matched.
 * [CYCLE-POINT-GLOB/]TASK-NAME-GLOB[:TASK-STATE]
 * [CYCLE-POINT-GLOB/]FAMILY-NAME-GLOB[:TASK-STATE]
 * TASK-NAME-GLOB[.CYCLE-POINT-GLOB][:TASK-STATE]
 * FAMILY-NAME-GLOB[.CYCLE-POINT-GLOB][:TASK-STATE]"""
     WITHOUT_CYCLE_GLOBS = """
+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
@@ -64,11 +70,9 @@ class CylcOptionParser(OptionParser):
 * all tasks in 'BAR' or 'BAZ' families: '20200202T0000Z/BA[RZ]' or
   'BA[RZ].20200202T0000Z'"""
     MULTITASKCYCLE_USAGE = MULTI_USAGE_TEMPLATE.format(
-        "", WITH_CYCLE_GLOBS, "", WITH_CYCLE_EXAMPLES)
+        WITH_CYCLE_GLOBS, WITH_CYCLE_EXAMPLES)
     MULTITASK_USAGE = MULTI_USAGE_TEMPLATE.format(
-        ", for a specific cycle point", WITHOUT_CYCLE_GLOBS,
-        ", within the given cycle point (e.g. '20200202T0000Z')",
-        WITHOUT_CYCLE_EXAMPLES)
+        WITHOUT_CYCLE_GLOBS, WITHOUT_CYCLE_EXAMPLES)
 
     def __init__(self, usage, argdoc=None, comms=False, noforce=False,
                  jset=False, multitask=False, multitask_nocycles=False,