Skip to content

Commit

Permalink
Clarify task ID glob help (#6606)
Browse files Browse the repository at this point in the history
Clarify task glob help.
  • Loading branch information
hjoliver authored Feb 14, 2025
1 parent ba6043d commit c8db7d1
Show file tree
Hide file tree
Showing 2 changed files with 11 additions and 12 deletions.
9 changes: 5 additions & 4 deletions cylc/flow/option_parsers.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
14 changes: 6 additions & 8 deletions cylc/flow/scripts/cylc.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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:
Expand All @@ -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"
Expand All @@ -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.
Expand Down

0 comments on commit c8db7d1

Please sign in to comment.