diff --git a/cylc/flow/option_parsers.py b/cylc/flow/option_parsers.py index 8a4245a6a9..c51221bc4e 100644 --- a/cylc/flow/option_parsers.py +++ b/cylc/flow/option_parsers.py @@ -242,19 +242,20 @@ class CylcOptionParser(OptionParser): MULTITASK_USAGE = dedent(''' This command can operate on multiple tasks. Globs and selectors may - be used to match active tasks: + be used to match tasks in the n=0 active window (except in the + `cylc show` command, where globs match in the wider n-window): Multiple Tasks: # Operate on two tasks workflow //cycle-1/task-1 //cycle-2/task-2 - Globs (note: globs should be quoted and only match active tasks): - # Match any active task "foo" in all cycles + Globs (note: quote globs; they only match in the active-window): + # Match any active-window task "foo" in all cycles '//*/foo' # Match the tasks "foo-1" and "foo-2" '//*/foo-[12]' - Selectors (note: selectors only match active tasks): + Selectors (note: selectors only match in the active window too): # match all failed tasks in cycle "1" //1:failed diff --git a/cylc/flow/scripts/cylc.py b/cylc/flow/scripts/cylc.py index e1e1855b84..213a715171 100644 --- a/cylc/flow/scripts/cylc.py +++ b/cylc/flow/scripts/cylc.py @@ -146,8 +146,7 @@ def get_version(long=False): $ cylc pause foo/run1 $ cylc stop foo/run1 - In the case of numbered runs (e.g. "run1", "run2", ...) you can omit - the run number, Cylc will infer latest run. + If you omit run number ("run1", "run2", ...) Cylc will infer latest run. $ cylc play foo $ cylc pause foo $ cylc stop foo @@ -164,8 +163,7 @@ def get_version(long=False): You can omit the user name when working on your own workflows. Cycle / Family / Task / Job IDs: - Just as workflows have IDs, the things within workflows have IDs too. - These IDs take the format: + Just as workflows have IDs, so do objects within workflows: cycle/task_or_family/job Examples: @@ -174,8 +172,7 @@ def get_version(long=False): 1/a/1 # The first job of the task "a" in the cycle point "1". Full ID - We join the workflow and cycle/task/job IDs together using //: - workflow//cycle/task/job + Join workflow and cycle/task/job IDs with //: workflow//cycle/task/job Examples: w// # The workflow "w" @@ -201,8 +198,9 @@ def get_version(long=False): workflow//cycle/task/* # All jobs in workflow//cycle/job Warning: - Remember to write IDs inside single quotes when using them on the - command line otherwise your shell may expand them. + Quote IDs on the command line to protect them from shell expansion. + Patterns only match tasks in the n=0 active window (except for the + `cylc show` command where they match in the wider n-window). Filters Filters allow you to filter for specific states.