From 02089421246012e0ae20b39b6be8efb9bfeafd20 Mon Sep 17 00:00:00 2001
From: Tim Pillinger <26465611+wxtim@users.noreply.github.com>
Date: Wed, 6 Oct 2021 15:27:02 +0100
Subject: [PATCH 01/14] write test for new WORKFLOW_ID=foo/run1 and
 WORKFLOW_NAME=foo

---
 Numbat                                        |  0
 Quokka                                        |  0
 Wambenger                                     |  0
 tests/functional/cylc-play/07-provided-vars.t | 55 +++++++++++++++++++
 4 files changed, 55 insertions(+)
 create mode 100644 Numbat
 create mode 100644 Quokka
 create mode 100644 Wambenger
 create mode 100644 tests/functional/cylc-play/07-provided-vars.t

diff --git a/Numbat b/Numbat
new file mode 100644
index 00000000000..e69de29bb2d
diff --git a/Quokka b/Quokka
new file mode 100644
index 00000000000..e69de29bb2d
diff --git a/Wambenger b/Wambenger
new file mode 100644
index 00000000000..e69de29bb2d
diff --git a/tests/functional/cylc-play/07-provided-vars.t b/tests/functional/cylc-play/07-provided-vars.t
new file mode 100644
index 00000000000..dd265340d27
--- /dev/null
+++ b/tests/functional/cylc-play/07-provided-vars.t
@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# THIS FILE IS PART OF THE CYLC WORKFLOW ENGINE.
+# Copyright (C) NIWA & British Crown (Met Office) & Contributors.
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#------------------------------------------------------------------------
+
+# test the export of CYLC_WORKFLOW_ID and CYLC_WORKFLOW_NAME
+
+. "$(dirname "$0")/test_header"
+
+set_test_number 4
+
+init_workflow "${TEST_NAME_BASE}" <<'__FLOW_CONFIG__'
+[scheduler]
+    cycle point format = %Y
+    [[events]]
+        stall timeout = PT0S
+
+[scheduling]
+    initial cycle point = 1066
+
+    [[dependencies]]
+        R1 = foo
+
+[runtime]
+    [[foo]]
+        script = """
+            echo "CYLC_WORKFLOW_NAME is: ${CYLC_WORKFLOW_NAME}"
+            echo "CYLC_WORKFLOW_ID is: ${CYLC_WORKFLOW_ID}"
+        """
+__FLOW_CONFIG__
+
+run_ok "${TEST_NAME_BASE}-validate" cylc validate "${WORKFLOW_NAME}"
+workflow_run_ok "${TEST_NAME_BASE}-play" cylc play "${WORKFLOW_NAME}" --no-detach
+named_grep_ok \
+    "${TEST_NAME_BASE}-check-CYLC_WORKFLOW_NAME" \
+    "CYLC_WORKFLOW_NAME is:.* ${WORKFLOW_NAME}" \
+    "${WORKFLOW_RUN_DIR}/log/job/1066/foo/NN/job.out"
+named_grep_ok \
+    "${TEST_NAME_BASE}-check-CYLC_WORKFLOW_ID" \
+    "CYLC_WORKFLOW_ID is:.* ${WORKFLOW_NAME}/run1" \
+    "${WORKFLOW_RUN_DIR}/log/job/1066/foo/NN/job.out"
+

From 85d75346cf9bc535598869e59ddb6c71194f1cd5 Mon Sep 17 00:00:00 2001
From: Tim Pillinger <26465611+wxtim@users.noreply.github.com>
Date: Thu, 7 Oct 2021 09:39:45 +0100
Subject: [PATCH 02/14] =?UTF-8?q?Renamed=20CYLC=5FWORKFLOW=5FNAME=20?=
 =?UTF-8?q?=E2=87=92=20CYLC=5FWORKFLOW=5FID=20Made=20CYLC=5FWORKFLOW=5FID?=
 =?UTF-8?q?=20=3D=20CYLC=5FWORKFLOW=5FNAME=20-=20trailing=20"runX"?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 cylc/flow/config.py    | 7 +++++--
 cylc/flow/pathutil.py  | 7 +++++++
 cylc/flow/scheduler.py | 7 +++++--
 3 files changed, 17 insertions(+), 4 deletions(-)

diff --git a/cylc/flow/config.py b/cylc/flow/config.py
index 1c749ebb0e4..4c1bb1becc8 100644
--- a/cylc/flow/config.py
+++ b/cylc/flow/config.py
@@ -75,6 +75,7 @@
     get_workflow_run_log_dir,
     get_workflow_run_share_dir,
     get_workflow_run_work_dir,
+    runN_remover
 )
 from cylc.flow.platforms import FORBIDDEN_WITH_PLATFORM
 from cylc.flow.print_tree import print_tree
@@ -182,7 +183,8 @@ def __init__(
         if self.mem_log is None:
             self.mem_log = lambda x: None
         self.mem_log("config.py:config.py: start init config")
-        self.workflow = workflow  # workflow name
+        self.workflow = workflow  # workflow id
+        self.workflow_name = runN_remover(self.workflow)
         self.fpath = str(fpath)  # workflow definition
         self.fdir = os.path.dirname(fpath)
         self.run_dir = run_dir or get_workflow_run_dir(self.workflow)
@@ -1353,7 +1355,8 @@ def process_workflow_env(self):
         """Workflow context is exported to the local environment."""
         for key, value in {
             **verbosity_to_env(cylc.flow.flags.verbosity),
-            'CYLC_WORKFLOW_NAME': self.workflow,
+            'CYLC_WORKFLOW_ID': self.workflow,
+            'CYLC_WORKFLOW_NAME': self.workflow_name,
             'CYLC_WORKFLOW_RUN_DIR': self.run_dir,
             'CYLC_WORKFLOW_LOG_DIR': self.log_dir,
             'CYLC_WORKFLOW_WORK_DIR': self.work_dir,
diff --git a/cylc/flow/pathutil.py b/cylc/flow/pathutil.py
index 1cca62ca66e..701459c7d57 100644
--- a/cylc/flow/pathutil.py
+++ b/cylc/flow/pathutil.py
@@ -409,3 +409,10 @@ def is_relative_to(path1: Union[Path, str], path2: Union[Path, str]) -> bool:
     except ValueError:
         return False
     return True
+
+
+def runN_remover(workflow_id: str) -> str:
+    if re.findall(r'(.*)\/run\d+$', workflow_id):
+        return re.findall(r'(.*)\/run\d+$', workflow_id)[0]
+    else:
+        return workflow_id
diff --git a/cylc/flow/scheduler.py b/cylc/flow/scheduler.py
index 0f6e39f649e..c9666dda18e 100644
--- a/cylc/flow/scheduler.py
+++ b/cylc/flow/scheduler.py
@@ -76,7 +76,8 @@
     get_workflow_run_share_dir,
     get_workflow_run_work_dir,
     get_workflow_test_log_name,
-    make_workflow_run_tree
+    make_workflow_run_tree,
+    runN_remover
 )
 from cylc.flow.platforms import (
     get_install_target_from_platform,
@@ -245,6 +246,7 @@ class Scheduler:
     def __init__(self, reg: str, options: Values) -> None:
         # flow information
         self.workflow = reg
+        self.workflow_name = runN_remover(self.workflow)
         self.owner = get_user()
         self.host = get_host()
         self.id = f'{self.owner}{ID_DELIM}{self.workflow}'
@@ -1104,7 +1106,8 @@ def load_flow_file(self, is_reload=False):
         self.task_job_mgr.job_file_writer.set_workflow_env({
             **verbosity_to_env(cylc.flow.flags.verbosity),
             'CYLC_UTC': str(get_utc_mode()),
-            'CYLC_WORKFLOW_NAME': self.workflow,
+            'CYLC_WORKFLOW_ID': self.workflow,
+            'CYLC_WORKFLOW_NAME': self.workflow_name,
             'CYLC_CYCLING_MODE': str(
                 self.config.cfg['scheduling']['cycling mode']
             ),

From 0aefd6069984b444f069b6e19a787a7544afd751 Mon Sep 17 00:00:00 2001
From: Tim Pillinger <26465611+wxtim@users.noreply.github.com>
Date: Thu, 7 Oct 2021 09:42:06 +0100
Subject: [PATCH 03/14] allow test_header init_workflow to set whether to use
 --no-run-name

---
 tests/functional/lib/bash/test_header | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/tests/functional/lib/bash/test_header b/tests/functional/lib/bash/test_header
index 77686102f15..562e227061b 100644
--- a/tests/functional/lib/bash/test_header
+++ b/tests/functional/lib/bash/test_header
@@ -453,12 +453,17 @@ graph_workflow() {
 init_workflow() {
     local TEST_NAME="$1"
     local FLOW_CONFIG="${2:--}"
+    local RUN_NUMS="${3:-false}"
     WORKFLOW_NAME="${CYLC_TEST_REG_BASE}/${TEST_SOURCE_DIR_BASE}/${TEST_NAME}"
     WORKFLOW_RUN_DIR="${RUN_DIR}/${WORKFLOW_NAME}"
     mkdir -p "${TEST_DIR}/${WORKFLOW_NAME}/"
     cat "${FLOW_CONFIG}" >"${TEST_DIR}/${WORKFLOW_NAME}/flow.cylc"
     cd "${TEST_DIR}/${WORKFLOW_NAME}"
-    cylc install --no-run-name --flow-name="${WORKFLOW_NAME}" --directory="${TEST_DIR}/${WORKFLOW_NAME}"
+    if "${RUN_NUMS}"; then
+        cylc install --flow-name="${WORKFLOW_NAME}" --directory="${TEST_DIR}/${WORKFLOW_NAME}"
+    else
+        cylc install --no-run-name --flow-name="${WORKFLOW_NAME}" --directory="${TEST_DIR}/${WORKFLOW_NAME}"
+    fi
 }
 
 install_workflow() {

From 0a3bbbd95cc38b4694adb1410daf47ef019125a6 Mon Sep 17 00:00:00 2001
From: Tim Pillinger <26465611+wxtim@users.noreply.github.com>
Date: Thu, 7 Oct 2021 09:42:33 +0100
Subject: [PATCH 04/14] fixed test for CYLC_WORKFLOW_ID

---
 tests/functional/cylc-play/07-provided-vars.t | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/tests/functional/cylc-play/07-provided-vars.t b/tests/functional/cylc-play/07-provided-vars.t
index dd265340d27..0ccb6400954 100644
--- a/tests/functional/cylc-play/07-provided-vars.t
+++ b/tests/functional/cylc-play/07-provided-vars.t
@@ -22,7 +22,7 @@
 
 set_test_number 4
 
-init_workflow "${TEST_NAME_BASE}" <<'__FLOW_CONFIG__'
+cat > flow.cylc <<'__FLOW_CONFIG__'
 [scheduler]
     cycle point format = %Y
     [[events]]
@@ -42,14 +42,16 @@ init_workflow "${TEST_NAME_BASE}" <<'__FLOW_CONFIG__'
         """
 __FLOW_CONFIG__
 
+init_workflow "${TEST_NAME_BASE}" flow.cylc true
+
 run_ok "${TEST_NAME_BASE}-validate" cylc validate "${WORKFLOW_NAME}"
 workflow_run_ok "${TEST_NAME_BASE}-play" cylc play "${WORKFLOW_NAME}" --no-detach
 named_grep_ok \
     "${TEST_NAME_BASE}-check-CYLC_WORKFLOW_NAME" \
     "CYLC_WORKFLOW_NAME is:.* ${WORKFLOW_NAME}" \
-    "${WORKFLOW_RUN_DIR}/log/job/1066/foo/NN/job.out"
+    "${WORKFLOW_RUN_DIR}/runN/log/job/1066/foo/NN/job.out"
 named_grep_ok \
     "${TEST_NAME_BASE}-check-CYLC_WORKFLOW_ID" \
     "CYLC_WORKFLOW_ID is:.* ${WORKFLOW_NAME}/run1" \
-    "${WORKFLOW_RUN_DIR}/log/job/1066/foo/NN/job.out"
+    "${WORKFLOW_RUN_DIR}/runN/log/job/1066/foo/NN/job.out"
 

From 56695ca2000d50e77f22289de2cd63475b70ab0f Mon Sep 17 00:00:00 2001
From: Tim Pillinger <26465611+wxtim@users.noreply.github.com>
Date: Thu, 7 Oct 2021 09:47:42 +0100
Subject: [PATCH 05/14] CHANGES.md added

---
 CHANGES.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/CHANGES.md b/CHANGES.md
index 5688a8786fd..f70a3a4ae45 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -100,6 +100,10 @@ workflow directory are recorded by `log/version`.
 [#4404](https://github.com/cylc/cylc-flow/pull/4404) - The Cylc Graph section
 now accepts ``&`` and ``|`` as valid line breaks in the same way as ``=>``.
 
+[#4455](https://github.com/cylc/cylc-flow/pull/4455) - `CYLC_WORKFLOW_NAME`
+renamed to `CYLC_WORKFLOW_ID`. `CYLC_WORKFLOW_NAME` re-added as
+`CYLC_WORKFLOW_ID` shorn of any trailing `runX`.
+
 
 ### Fixes
 

From e76b043dce1b28fd15e1f26eb53cb2328b02b45c Mon Sep 17 00:00:00 2001
From: Tim Pillinger <26465611+wxtim@users.noreply.github.com>
Date: Thu, 7 Oct 2021 14:16:23 +0100
Subject: [PATCH 06/14] Apply suggestions from code review

Co-authored-by: Ronnie Dutta <61982285+MetRonnie@users.noreply.github.com>
---
 cylc/flow/pathutil.py | 7 ++-----
 1 file changed, 2 insertions(+), 5 deletions(-)

diff --git a/cylc/flow/pathutil.py b/cylc/flow/pathutil.py
index 701459c7d57..c6a83c65f15 100644
--- a/cylc/flow/pathutil.py
+++ b/cylc/flow/pathutil.py
@@ -411,8 +411,5 @@ def is_relative_to(path1: Union[Path, str], path2: Union[Path, str]) -> bool:
     return True
 
 
-def runN_remover(workflow_id: str) -> str:
-    if re.findall(r'(.*)\/run\d+$', workflow_id):
-        return re.findall(r'(.*)\/run\d+$', workflow_id)[0]
-    else:
-        return workflow_id
+def get_workflow_name_from_id(workflow_id: str) -> str:
+    return re.sub(rf'{re.escape(os.sep)}run\d+$', '', workflow_id)

From a48be6f0fa6d6d9b2111365a35e3ab74f53121d9 Mon Sep 17 00:00:00 2001
From: Tim Pillinger <26465611+wxtim@users.noreply.github.com>
Date: Thu, 7 Oct 2021 14:22:31 +0100
Subject: [PATCH 07/14] remove unwanted files; add documentation for change to
 init_workflow

---
 Numbat                                | 0
 Quokka                                | 0
 Wambenger                             | 0
 tests/functional/lib/bash/test_header | 3 ++-
 4 files changed, 2 insertions(+), 1 deletion(-)
 delete mode 100644 Numbat
 delete mode 100644 Quokka
 delete mode 100644 Wambenger

diff --git a/Numbat b/Numbat
deleted file mode 100644
index e69de29bb2d..00000000000
diff --git a/Quokka b/Quokka
deleted file mode 100644
index e69de29bb2d..00000000000
diff --git a/Wambenger b/Wambenger
deleted file mode 100644
index e69de29bb2d..00000000000
diff --git a/tests/functional/lib/bash/test_header b/tests/functional/lib/bash/test_header
index 562e227061b..d7ba6e2dc5b 100644
--- a/tests/functional/lib/bash/test_header
+++ b/tests/functional/lib/bash/test_header
@@ -73,10 +73,11 @@
 #         Test that FILE exists
 #     exists_fail FILE
 #         Test that FILE does not exist
-#     init_workflow TEST_NAME [SOURCE]
+#     init_workflow TEST_NAME [SOURCE] [[RUN_NUMS]]
 #         Create a workflow from SOURCE's "flow.cylc" called:
 #         "cylctb-${CYLC_TEST_TIME_INIT}/${TEST_SOURCE_DIR##*tests/}/${TEST_NAME}"
 #         Provides WORKFLOW_NAME and WORKFLOW_RUN_DIR variables.
+#         RUN_NUMS (defaults to false): If false run cylc install --no-rundir
 #     install_workflow TEST_NAME SOURCE
 #         Same as init_workflow, but SOURCE must be a directory containing a
 #         "flow.cylc" file.

From ba37e34b9899d6b52cee84e3400fec538d375568 Mon Sep 17 00:00:00 2001
From: Tim Pillinger <26465611+wxtim@users.noreply.github.com>
Date: Thu, 7 Oct 2021 14:30:54 +0100
Subject: [PATCH 08/14] finished rename of runN_remover

---
 cylc/flow/config.py    | 4 ++--
 cylc/flow/scheduler.py | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/cylc/flow/config.py b/cylc/flow/config.py
index 4c1bb1becc8..0d58d96c573 100644
--- a/cylc/flow/config.py
+++ b/cylc/flow/config.py
@@ -75,7 +75,7 @@
     get_workflow_run_log_dir,
     get_workflow_run_share_dir,
     get_workflow_run_work_dir,
-    runN_remover
+    get_workflow_name_from_id
 )
 from cylc.flow.platforms import FORBIDDEN_WITH_PLATFORM
 from cylc.flow.print_tree import print_tree
@@ -184,7 +184,7 @@ def __init__(
             self.mem_log = lambda x: None
         self.mem_log("config.py:config.py: start init config")
         self.workflow = workflow  # workflow id
-        self.workflow_name = runN_remover(self.workflow)
+        self.workflow_name = get_workflow_name_from_id(self.workflow)
         self.fpath = str(fpath)  # workflow definition
         self.fdir = os.path.dirname(fpath)
         self.run_dir = run_dir or get_workflow_run_dir(self.workflow)
diff --git a/cylc/flow/scheduler.py b/cylc/flow/scheduler.py
index c9666dda18e..58d85b0132e 100644
--- a/cylc/flow/scheduler.py
+++ b/cylc/flow/scheduler.py
@@ -77,7 +77,7 @@
     get_workflow_run_work_dir,
     get_workflow_test_log_name,
     make_workflow_run_tree,
-    runN_remover
+    get_workflow_name_from_id
 )
 from cylc.flow.platforms import (
     get_install_target_from_platform,
@@ -246,7 +246,7 @@ class Scheduler:
     def __init__(self, reg: str, options: Values) -> None:
         # flow information
         self.workflow = reg
-        self.workflow_name = runN_remover(self.workflow)
+        self.workflow_name = get_workflow_name_from_id(self.workflow)
         self.owner = get_user()
         self.host = get_host()
         self.id = f'{self.owner}{ID_DELIM}{self.workflow}'

From 33ae4aece9671aab9275614473d60c3a128eea2b Mon Sep 17 00:00:00 2001
From: Tim Pillinger <26465611+wxtim@users.noreply.github.com>
Date: Fri, 8 Oct 2021 11:05:32 +0100
Subject: [PATCH 09/14] added docstring as per @metronnie suggestion

---
 cylc/flow/pathutil.py                                   | 8 ++++++++
 tests/flakyfunctional/xtriggers/00-wall_clock.t         | 3 +++
 tests/flakyfunctional/xtriggers/00-wall_clock/flow.cylc | 2 +-
 3 files changed, 12 insertions(+), 1 deletion(-)

diff --git a/cylc/flow/pathutil.py b/cylc/flow/pathutil.py
index c6a83c65f15..9dbfc17460e 100644
--- a/cylc/flow/pathutil.py
+++ b/cylc/flow/pathutil.py
@@ -412,4 +412,12 @@ def is_relative_to(path1: Union[Path, str], path2: Union[Path, str]) -> bool:
 
 
 def get_workflow_name_from_id(workflow_id: str) -> str:
+    """Workflow name is the ID shorn of the runN directory name.
+
+    Examples:
+    >>> get_workflow_name_from_id('my_workflow/run42')
+    'my_workflow'
+    >>> get_workflow_name_from_id('my_other_workflow')
+    'my_other_workflow'
+    """
     return re.sub(rf'{re.escape(os.sep)}run\d+$', '', workflow_id)
diff --git a/tests/flakyfunctional/xtriggers/00-wall_clock.t b/tests/flakyfunctional/xtriggers/00-wall_clock.t
index efc99257b7c..1262b4f1685 100644
--- a/tests/flakyfunctional/xtriggers/00-wall_clock.t
+++ b/tests/flakyfunctional/xtriggers/00-wall_clock.t
@@ -33,6 +33,9 @@ START="$NOW"
 HOUR="$(date +%H)"
 OFFSET="PT0S"
 
+# Spoof an unusual timezone
+export TZ=Asia/Kathmandu
+
 run_ok "${TEST_NAME_BASE}-val" cylc validate "${WORKFLOW_NAME}" \
    -s "START='${START}'" -s "HOUR='${HOUR}'" -s "OFFSET='${OFFSET}'"
 
diff --git a/tests/flakyfunctional/xtriggers/00-wall_clock/flow.cylc b/tests/flakyfunctional/xtriggers/00-wall_clock/flow.cylc
index 5c3c8c5e80e..1e45c8d9741 100644
--- a/tests/flakyfunctional/xtriggers/00-wall_clock/flow.cylc
+++ b/tests/flakyfunctional/xtriggers/00-wall_clock/flow.cylc
@@ -4,7 +4,7 @@
 # clock trigger is not satisfied, else stall and abort.
 
 [scheduler]
-    UTC mode = False
+    cycle point time zone = '+0545'
     [[events]]
         abort on inactivity timeout = True
         inactivity timeout = PT15S

From bbded6e63dbaf0d7dc7006252f934af984eba843 Mon Sep 17 00:00:00 2001
From: Tim Pillinger <26465611+wxtim@users.noreply.github.com>
Date: Fri, 8 Oct 2021 13:51:19 +0100
Subject: [PATCH 10/14] remove accidental PR pollution

---
 tests/flakyfunctional/xtriggers/00-wall_clock.t         | 3 ---
 tests/flakyfunctional/xtriggers/00-wall_clock/flow.cylc | 2 +-
 2 files changed, 1 insertion(+), 4 deletions(-)

diff --git a/tests/flakyfunctional/xtriggers/00-wall_clock.t b/tests/flakyfunctional/xtriggers/00-wall_clock.t
index 1262b4f1685..efc99257b7c 100644
--- a/tests/flakyfunctional/xtriggers/00-wall_clock.t
+++ b/tests/flakyfunctional/xtriggers/00-wall_clock.t
@@ -33,9 +33,6 @@ START="$NOW"
 HOUR="$(date +%H)"
 OFFSET="PT0S"
 
-# Spoof an unusual timezone
-export TZ=Asia/Kathmandu
-
 run_ok "${TEST_NAME_BASE}-val" cylc validate "${WORKFLOW_NAME}" \
    -s "START='${START}'" -s "HOUR='${HOUR}'" -s "OFFSET='${OFFSET}'"
 
diff --git a/tests/flakyfunctional/xtriggers/00-wall_clock/flow.cylc b/tests/flakyfunctional/xtriggers/00-wall_clock/flow.cylc
index 1e45c8d9741..5c3c8c5e80e 100644
--- a/tests/flakyfunctional/xtriggers/00-wall_clock/flow.cylc
+++ b/tests/flakyfunctional/xtriggers/00-wall_clock/flow.cylc
@@ -4,7 +4,7 @@
 # clock trigger is not satisfied, else stall and abort.
 
 [scheduler]
-    cycle point time zone = '+0545'
+    UTC mode = False
     [[events]]
         abort on inactivity timeout = True
         inactivity timeout = PT15S

From 2b802cd0416ec6e9044d3a1beb7c2fbcfe1699dc Mon Sep 17 00:00:00 2001
From: Tim Pillinger <26465611+wxtim@users.noreply.github.com>
Date: Fri, 8 Oct 2021 16:10:45 +0100
Subject: [PATCH 11/14] replaced refs in script docstrings to REG to
 WORKFLOW/ID/NAME

---
 cylc/flow/scripts/broadcast.py            | 10 +++++-----
 cylc/flow/scripts/cat_log.py              |  2 +-
 cylc/flow/scripts/clean.py                |  2 +-
 cylc/flow/scripts/client.py               |  2 +-
 cylc/flow/scripts/config.py               |  7 ++++---
 cylc/flow/scripts/ext_trigger.py          |  2 +-
 cylc/flow/scripts/get_workflow_contact.py |  2 +-
 cylc/flow/scripts/hold.py                 |  2 +-
 cylc/flow/scripts/install.py              | 18 +++++++++---------
 cylc/flow/scripts/kill.py                 |  6 +++---
 cylc/flow/scripts/message.py              |  2 +-
 cylc/flow/scripts/pause.py                |  2 +-
 cylc/flow/scripts/ping.py                 |  8 ++++++--
 cylc/flow/scripts/poll.py                 |  6 +++---
 cylc/flow/scripts/reinstall.py            |  2 +-
 cylc/flow/scripts/release.py              |  2 +-
 cylc/flow/scripts/reload.py               |  4 ++--
 cylc/flow/scripts/remove.py               |  2 +-
 cylc/flow/scripts/report_timings.py       |  2 +-
 cylc/flow/scripts/set_outputs.py          |  2 +-
 cylc/flow/scripts/set_verbosity.py        |  2 +-
 cylc/flow/scripts/show.py                 |  8 ++++----
 cylc/flow/scripts/stop.py                 |  2 +-
 cylc/flow/scripts/subscribe.py            |  2 +-
 cylc/flow/scripts/trigger.py              |  7 ++++---
 cylc/flow/scripts/tui.py                  |  4 ++--
 cylc/flow/scripts/workflow_state.py       | 10 +++++-----
 27 files changed, 63 insertions(+), 57 deletions(-)

diff --git a/cylc/flow/scripts/broadcast.py b/cylc/flow/scripts/broadcast.py
index be187e08284..d589d43c0b5 100755
--- a/cylc/flow/scripts/broadcast.py
+++ b/cylc/flow/scripts/broadcast.py
@@ -48,20 +48,20 @@
 
 Examples:
   # To broadcast a variable to all tasks (quote items with internal spaces):
-  $ cylc broadcast -s "[environment]VERSE = the quick brown fox" REG
+  $ cylc broadcast -s "[environment]VERSE = the quick brown fox" WORKFLOW
 
   # To do the same with a file:
   $ cat >'broadcast.cylc' <<'__FLOW__'
   $ [environment]
   $     VERSE = the quick brown fox
   $ __FLOW__
-  $ cylc broadcast -F 'broadcast.cylc' REG
+  $ cylc broadcast -F 'broadcast.cylc' WORKFLOW
 
   # To cancel the same broadcast:
-  $ cylc broadcast --cancel "[environment]VERSE" REG
+  $ cylc broadcast --cancel "[environment]VERSE" WORKFLOW
 
   # If -F FILE was used, the same file can be used to cancel the broadcast:
-  $ cylc broadcast -G 'broadcast.cylc' REG
+  $ cylc broadcast -G 'broadcast.cylc' WORKFLOW
 
 Use -d/--display to see active broadcasts. Multiple --cancel options or
 multiple --set and --set-file options can be used on the same command line.
@@ -224,7 +224,7 @@ def get_option_parser():
     """CLI for "cylc broadcast"."""
     parser = COP(
         __doc__, comms=True,
-        argdoc=[('REG', "Workflow name")]
+        argdoc=[('WORKFLOW', 'Workflow name or ID')]
     )
 
     parser.add_option(
diff --git a/cylc/flow/scripts/cat_log.py b/cylc/flow/scripts/cat_log.py
index f5b136deb20..ade52ce5cee 100755
--- a/cylc/flow/scripts/cat_log.py
+++ b/cylc/flow/scripts/cat_log.py
@@ -225,7 +225,7 @@ def get_option_parser():
     parser = COP(
         __doc__,
         argdoc=[
-            ("REG", "Workflow name"),
+            ("WORKFLOW", "Workflow name or ID"),
             ("[TASK-ID]", """Task ID""")
         ]
     )
diff --git a/cylc/flow/scripts/clean.py b/cylc/flow/scripts/clean.py
index 4a910f362a5..5b40177e420 100644
--- a/cylc/flow/scripts/clean.py
+++ b/cylc/flow/scripts/clean.py
@@ -71,7 +71,7 @@
 def get_option_parser():
     parser = COP(
         __doc__,
-        argdoc=[('REG', "Workflow name")],
+        argdoc=[('WORKFLOW', 'Workflow name or ID')],
         segregated_log=True
     )
 
diff --git a/cylc/flow/scripts/client.py b/cylc/flow/scripts/client.py
index 244c18f3ace..4a4335b14bc 100755
--- a/cylc/flow/scripts/client.py
+++ b/cylc/flow/scripts/client.py
@@ -44,7 +44,7 @@
 
 def get_option_parser():
     parser = COP(__doc__, comms=True, argdoc=[
-        ('REG', 'Workflow name'),
+        ('WORKFLOW', 'Workflow name or ID'),
         ('METHOD', 'Network API function name')])
 
     parser.add_option(
diff --git a/cylc/flow/scripts/config.py b/cylc/flow/scripts/config.py
index 9380ec49d58..ca545a18dc1 100755
--- a/cylc/flow/scripts/config.py
+++ b/cylc/flow/scripts/config.py
@@ -20,8 +20,9 @@
 
 Parse and print Cylc configuration files.
 
-Print parsed configuration, after runtime inheritance. If REG is specified,
-print the workflow configuration, otherwise print the global configuration.
+Print parsed configuration, after runtime inheritance. If WORKFLOW is
+specified, print the workflow configuration, otherwise print the global
+configuration.
 
 Note:
   This is different to `cylc view` which doesn't parse the configuration,
@@ -66,7 +67,7 @@
 def get_option_parser():
     parser = COP(
         __doc__,
-        argdoc=[("[REG]", "Workflow name or path")],
+        argdoc=[("[WORKFLOW]", "Workflow name or path")],
         jset=True, icp=True
     )
 
diff --git a/cylc/flow/scripts/ext_trigger.py b/cylc/flow/scripts/ext_trigger.py
index 12fa42b9705..a10595d34a0 100755
--- a/cylc/flow/scripts/ext_trigger.py
+++ b/cylc/flow/scripts/ext_trigger.py
@@ -75,7 +75,7 @@
 def get_option_parser():
     parser = COP(
         __doc__, comms=True,
-        argdoc=[("REG", "Workflow name"),
+        argdoc=[("WORKFLOW", "Workflow name or ID"),
                 ("MSG", "External trigger message"),
                 ("ID", "Unique trigger ID")])
 
diff --git a/cylc/flow/scripts/get_workflow_contact.py b/cylc/flow/scripts/get_workflow_contact.py
index e206e170b88..be1f41f063e 100755
--- a/cylc/flow/scripts/get_workflow_contact.py
+++ b/cylc/flow/scripts/get_workflow_contact.py
@@ -32,7 +32,7 @@
 
 
 def get_option_parser():
-    return COP(__doc__, argdoc=[('REG', 'Workflow name')])
+    return COP(__doc__, argdoc=[('WORKFLOW', 'Workflow name or ID')])
 
 
 @cli_function(get_option_parser)
diff --git a/cylc/flow/scripts/hold.py b/cylc/flow/scripts/hold.py
index d616e92337b..192ab3992c2 100755
--- a/cylc/flow/scripts/hold.py
+++ b/cylc/flow/scripts/hold.py
@@ -97,7 +97,7 @@ def get_option_parser() -> COP:
     parser = COP(
         __doc__, comms=True, multitask=True,
         argdoc=[
-            ('REG', "Workflow name"),
+            ('WORKFLOW', 'Workflow name or ID'),
             # TODO: switch back to TASK_ID?
             ('[TASK_GLOB ...]', "Task matching patterns")]
     )
diff --git a/cylc/flow/scripts/install.py b/cylc/flow/scripts/install.py
index 41248857c34..aa2e1cc6ba8 100755
--- a/cylc/flow/scripts/install.py
+++ b/cylc/flow/scripts/install.py
@@ -22,18 +22,18 @@
 
 The workflow can then be started, stopped, and targeted by name.
 
-Normal installation creates a directory "~/cylc-run/REG/", with a run
-directory "~/cylc-run/REG/run1". A "_cylc-install/source" symlink to the source
-directory will be created in the REG directory.
+Normal installation creates a directory "~/cylc-run/WORKFLOW_NAME/", with a run
+directory "~/cylc-run/WORKFLOW_NAME/run1". A "_cylc-install/source" symlink to
+the source directory will be created in the WORKFLOW_NAME directory.
 Any files or directories (excluding .git, .svn) from the source directory are
 copied to the new run directory.
 A ".service" directory will also be created and used for server authentication
 files at run time.
 
-If the argument REG is used, Cylc will search for the workflow in the list of
-directories given by "global.cylc[install]source dirs", and install the first
-match. Otherwise, the workflow in the current working directory, or the one
-specified by the "--directory" option, will be installed.
+If the argument WORKFLOW_NAME is used, Cylc will search for the workflow in the
+list of directories given by "global.cylc[install]source dirs", and install the
+first match. Otherwise, the workflow in the current working directory, or the
+one specified by the "--directory" option, will be installed.
 
 Workflow names can be hierarchical, corresponding to the path under ~/cylc-run.
 
@@ -86,7 +86,7 @@
 def get_option_parser():
     parser = COP(
         __doc__, comms=True, prep=True,
-        argdoc=[("[REG]", "Workflow name")]
+        argdoc=[('[WORKFLOW]', 'Workflow name or ID')]
     )
 
     parser.add_option(
@@ -153,7 +153,7 @@ def install(
         source = opts.source
     else:
         if opts.source:
-            parser.error("REG and --directory are mutually exclusive.")
+            parser.error("WORKFLOW and --directory are mutually exclusive.")
         source = search_install_source_dirs(reg)
     flow_name = opts.flow_name or reg
 
diff --git a/cylc/flow/scripts/kill.py b/cylc/flow/scripts/kill.py
index 66a8149412d..1dce95d43a2 100755
--- a/cylc/flow/scripts/kill.py
+++ b/cylc/flow/scripts/kill.py
@@ -21,8 +21,8 @@
 Kill running or submitted jobs.
 
 Examples:
-  $ cylc kill REG  # kill all active tasks in the workflow
-  $ cylc kill REG TASK_GLOB ...  # kill one or more active tasks
+  $ cylc kill WORKFLOW  # kill all active tasks in the workflow
+  $ cylc kill WORKFLOW TASK_GLOB ...  # kill one or more active tasks
 """
 
 from typing import TYPE_CHECKING
@@ -55,7 +55,7 @@ def get_option_parser():
     parser = COP(
         __doc__, comms=True, multitask=True,
         argdoc=[
-            ('REG', 'Workflow name'),
+            ('WORKFLOW', 'Workflow name or ID'),
             ('[TASK_GLOB ...]', 'Task matching patterns')])
 
     return parser
diff --git a/cylc/flow/scripts/message.py b/cylc/flow/scripts/message.py
index 3d19de14275..2289ceeb163 100755
--- a/cylc/flow/scripts/message.py
+++ b/cylc/flow/scripts/message.py
@@ -90,7 +90,7 @@ def get_option_parser():
     parser = COP(
         __doc__, comms=True,
         argdoc=[
-            ('[REG]', 'Workflow name'),
+            ('[WORKFLOW]', 'Workflow name or ID'),
             ('[TASK-JOB]', 'Task job identifier CYCLE/TASK_NAME/SUBMIT_NUM'),
             ('[[SEVERITY:]MESSAGE ...]', 'Messages')])
     parser.add_option(
diff --git a/cylc/flow/scripts/pause.py b/cylc/flow/scripts/pause.py
index 0c0c363f30c..c8c95529aab 100644
--- a/cylc/flow/scripts/pause.py
+++ b/cylc/flow/scripts/pause.py
@@ -57,7 +57,7 @@
 def get_option_parser():
     parser = COP(
         __doc__, comms=True, multitask=True,
-        argdoc=[('REG', "Workflow name")]
+        argdoc=[('WORKFLOW', 'Workflow name or ID')]
     )
     return parser
 
diff --git a/cylc/flow/scripts/ping.py b/cylc/flow/scripts/ping.py
index 7e2366effb0..bf31ff78765 100755
--- a/cylc/flow/scripts/ping.py
+++ b/cylc/flow/scripts/ping.py
@@ -20,7 +20,7 @@
 
 Test communication with a running workflow.
 
-If workflow REG is running or TASK in workflow REG is currently running,
+If workflow WORKFLOW is running or TASK in WORKFLOW is currently running,
 exit with success status, else exit with error status."""
 
 from ansimarkup import parse as cparse
@@ -65,7 +65,11 @@
 def get_option_parser():
     parser = COP(
         __doc__, comms=True,
-        argdoc=[('REG', 'Workflow name'), ('[TASK]', 'Task ' + TaskID.SYNTAX)])
+        argdoc=[
+            ('WORKFLOW', 'Workflow name or ID'),
+            ('[TASK]', 'Task ' + TaskID.SYNTAX)
+        ]
+    )
 
     return parser
 
diff --git a/cylc/flow/scripts/poll.py b/cylc/flow/scripts/poll.py
index df153d1b32b..c7e0cd3be95 100755
--- a/cylc/flow/scripts/poll.py
+++ b/cylc/flow/scripts/poll.py
@@ -21,8 +21,8 @@
 Poll (query) task jobs to verify and update their statuses.
 
 Examples:
-  $ cylc poll REG  # poll all active tasks
-  $ cylc poll REG TASK_GLOB  # poll multiple active tasks or families
+  $ cylc poll WORKFLOW  # poll all active tasks
+  $ cylc poll WORKFLOW TASK_GLOB  # poll multiple active tasks or families
 """
 
 from typing import TYPE_CHECKING
@@ -55,7 +55,7 @@ def get_option_parser():
     parser = COP(
         __doc__, comms=True, multitask=True,
         argdoc=[
-            ('REG', 'Workflow name'),
+            ('WORKFLOW', 'Workflow name or ID'),
             ('[TASK_GLOB ...]', 'Task matching patterns')]
     )
     return parser
diff --git a/cylc/flow/scripts/reinstall.py b/cylc/flow/scripts/reinstall.py
index 8f63474071f..8f6c5b06a1c 100644
--- a/cylc/flow/scripts/reinstall.py
+++ b/cylc/flow/scripts/reinstall.py
@@ -58,7 +58,7 @@
 
 def get_option_parser():
     parser = COP(
-        __doc__, comms=True, argdoc=[('[REG]', 'Workflow name')]
+        __doc__, comms=True, argdoc=[('[WORKFLOW]', 'Workflow name or ID')]
     )
 
     parser.add_cylc_rose_options()
diff --git a/cylc/flow/scripts/release.py b/cylc/flow/scripts/release.py
index b6ed2ec4fcf..cef6b07cd0c 100755
--- a/cylc/flow/scripts/release.py
+++ b/cylc/flow/scripts/release.py
@@ -84,7 +84,7 @@ def get_option_parser() -> COP:
     parser = COP(
         __doc__, comms=True, multitask=True,
         argdoc=[
-            ('REG', "Workflow name"),
+            ('WORKFLOW', 'Workflow name or ID'),
             ('[TASK_GLOB ...]', "Task matching patterns")]
     )
 
diff --git a/cylc/flow/scripts/reload.py b/cylc/flow/scripts/reload.py
index a92088d3867..4afebf4993f 100755
--- a/cylc/flow/scripts/reload.py
+++ b/cylc/flow/scripts/reload.py
@@ -26,8 +26,8 @@
 a task is already running at reload time.
 
 If the workflow was started with Jinja2 template variables set on the command
-line (cylc play --set 'FOO="bar"' REG) the same template settings apply to the
-reload (only changes to the flow.cylc file itself are reloaded).
+line (cylc play --set 'FOO="bar"' WORKFLOW) the same template settings apply to
+the reload (only changes to the flow.cylc file itself are reloaded).
 
 If the modified workflow definition does not parse, failure to reload will
 be reported but no harm will be done to the running workflow."""
diff --git a/cylc/flow/scripts/remove.py b/cylc/flow/scripts/remove.py
index ebb70588ed8..765a27c8604 100755
--- a/cylc/flow/scripts/remove.py
+++ b/cylc/flow/scripts/remove.py
@@ -52,7 +52,7 @@ def get_option_parser():
     parser = COP(
         __doc__, comms=True, multitask=True,
         argdoc=[
-            ("REG", "Workflow name"),
+            ("WORKFLOW", "Workflow name or ID"),
             ('TASK_GLOB [...]', 'Task matching patterns')])
 
     return parser
diff --git a/cylc/flow/scripts/report_timings.py b/cylc/flow/scripts/report_timings.py
index 2ab57b6b3a3..7eaec3bae76 100755
--- a/cylc/flow/scripts/report_timings.py
+++ b/cylc/flow/scripts/report_timings.py
@@ -89,7 +89,7 @@ def smart_open(filename=None):
 def get_option_parser():
     parser = COP(
         __doc__,
-        argdoc=[('REG', 'Workflow name')]
+        argdoc=[('WORKFLOW', 'Workflow name or ID')]
     )
     parser.add_option(
         "-r", "--raw",
diff --git a/cylc/flow/scripts/set_outputs.py b/cylc/flow/scripts/set_outputs.py
index 070503f0b3c..5190207a599 100755
--- a/cylc/flow/scripts/set_outputs.py
+++ b/cylc/flow/scripts/set_outputs.py
@@ -58,7 +58,7 @@ def get_option_parser():
     parser = COP(
         __doc__, comms=True, multitask_nocycles=True,
         argdoc=[
-            ("REG", "Workflow name"),
+            ("WORKFLOW", "Workflow name or ID"),
             ('TASK-GLOB [...]', 'Task match pattern')])
     parser.add_option(
         "--output", metavar="OUTPUT",
diff --git a/cylc/flow/scripts/set_verbosity.py b/cylc/flow/scripts/set_verbosity.py
index c5be32dccd0..868b82bdf59 100755
--- a/cylc/flow/scripts/set_verbosity.py
+++ b/cylc/flow/scripts/set_verbosity.py
@@ -52,7 +52,7 @@ def get_option_parser():
     parser = COP(
         __doc__, comms=True,
         argdoc=[
-            ('REG', 'Workflow name'),
+            ('WORKFLOW', 'Workflow name or ID'),
             ('LEVEL', ', '.join(LOG_LEVELS.keys()))
         ]
     )
diff --git a/cylc/flow/scripts/show.py b/cylc/flow/scripts/show.py
index c83ca4cba9a..e51f474fd8b 100755
--- a/cylc/flow/scripts/show.py
+++ b/cylc/flow/scripts/show.py
@@ -21,9 +21,9 @@
 Display workflow and task information.
 
 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 task instances
+  $ cylc show WORKFLOW  # workflow metadata
+  $ cylc show WORKFLOW TASK_NAME  # task metadata
+  $ cylc show WORKFLOW TASK_GLOB  # prerequisites and outputs of task instances
 
 Prerequisite and output status is indicated for current active tasks.
 """
@@ -143,7 +143,7 @@ def get_option_parser():
     parser = COP(
         __doc__, comms=True, multitask=True,
         argdoc=[
-            ('REG', 'Workflow name'),
+            ('WORKFLOW', 'Workflow name or ID'),
             ('[TASK_NAME or TASK_GLOB ...]', 'Task names or match patterns')])
 
     parser.add_option('--list-prereqs', action="store_true", default=False,
diff --git a/cylc/flow/scripts/stop.py b/cylc/flow/scripts/stop.py
index 85f14a25db3..fe9b6fcbf3a 100755
--- a/cylc/flow/scripts/stop.py
+++ b/cylc/flow/scripts/stop.py
@@ -112,7 +112,7 @@ def check(self):
 def get_option_parser():
     parser = COP(
         __doc__, comms=True,
-        argdoc=[("REG", "Workflow name"),
+        argdoc=[("WORKFLOW", "Workflow name or ID"),
                 ("[STOP]", "task POINT (cycle point), or TASK (task ID).")]
     )
 
diff --git a/cylc/flow/scripts/subscribe.py b/cylc/flow/scripts/subscribe.py
index d77aca6cc02..a825c46105b 100755
--- a/cylc/flow/scripts/subscribe.py
+++ b/cylc/flow/scripts/subscribe.py
@@ -57,7 +57,7 @@ def get_option_parser():
     parser = COP(
         __doc__,
         argdoc=[
-            ('REG', 'Workflow name')
+            ('WORKFLOW', 'Workflow name or ID')
         ],
         comms=True
     )
diff --git a/cylc/flow/scripts/trigger.py b/cylc/flow/scripts/trigger.py
index b4edc9b9248..5a8f86017f4 100755
--- a/cylc/flow/scripts/trigger.py
+++ b/cylc/flow/scripts/trigger.py
@@ -20,8 +20,9 @@
 Manually trigger tasks.
 
 Examples:
-  $ cylc trigger REG  # trigger all tasks in a running workflow
-  $ cylc trigger REG TASK_GLOB ...  # trigger some tasks in a running workflow
+  $ cylc trigger WORKFLOW  # trigger all tasks in a running workflow
+  # trigger some tasks in a running workflow:
+  $ cylc trigger WORKFLOW TASK_GLOB ...
 
 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
@@ -62,7 +63,7 @@ def get_option_parser():
     parser = COP(
         __doc__, comms=True, multitask_nocycles=True,
         argdoc=[
-            ('REG', 'Workflow name'),
+            ('WORKFLOW', 'Workflow name or ID'),
             ('[TASK_GLOB ...]', 'Task matching patterns')])
 
     parser.add_option(
diff --git a/cylc/flow/scripts/tui.py b/cylc/flow/scripts/tui.py
index 788e0dc5f75..09263198a7c 100644
--- a/cylc/flow/scripts/tui.py
+++ b/cylc/flow/scripts/tui.py
@@ -15,7 +15,7 @@
 # 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 tui REG
+"""cylc tui WORKFLOW
 
 View and control running workflows in the terminal.
 
@@ -53,7 +53,7 @@ def get_option_parser():
     parser = COP(
         __doc__,
         argdoc=[
-            ('REG', 'Workflow name')
+            ('WORKFLOW', 'Workflow name or ID')
         ],
         # auto_add=False,  NOTE: at present auto_add can not be turned off
         color=False
diff --git a/cylc/flow/scripts/workflow_state.py b/cylc/flow/scripts/workflow_state.py
index 21ee65b0d0a..d87f557c3d4 100755
--- a/cylc/flow/scripts/workflow_state.py
+++ b/cylc/flow/scripts/workflow_state.py
@@ -35,15 +35,15 @@
 mirrored workflow databases, use --run-dir=DIR to specify the location.
 
 Examples:
-  $ cylc workflow-state REG --task=TASK --point=POINT --status=STATUS
+  $ cylc workflow-state WORKFLOW --task=TASK --point=POINT --status=STATUS
   # returns 0 if TASK.POINT reaches STATUS before the maximum number of
   # polls, otherwise returns 1.
 
-  $ cylc workflow-state REG --task=TASK --point=POINT --status=STATUS \
+  $ cylc workflow-state WORKFLOW --task=TASK --point=POINT --status=STATUS \
   > --offset=PT6H
   # adds 6 hours to the value of CYCLE for carrying out the polling operation.
 
-  $ cylc workflow-state REG --task=TASK --status=STATUS --task-point
+  $ cylc workflow-state WORKFLOW --task=TASK --status=STATUS --task-point
   # uses CYLC_TASK_CYCLE_POINT environment variable as the value for the
   # CYCLE to poll. This is useful when you want to use cylc workflow-state in a
   # cylc task.
@@ -128,7 +128,7 @@ def check(self):
 def get_option_parser() -> COP:
     parser = COP(
         __doc__,
-        argdoc=[('REG', "Workflow name")]
+        argdoc=[('WORKFLOW', "Workflow name or ID")]
     )
 
     parser.add_option(
@@ -150,7 +150,7 @@ def get_option_parser() -> COP:
     parser.add_option(
         "-d", "--run-dir",
         help="The top level cylc run directory if non-standard. The "
-             "database should be DIR/REG/log/db. Use to interrogate "
+             "database should be DIR/WORKFLOW_ID/log/db. Use to interrogate "
              "workflows owned by others, etc.; see note above.",
         metavar="DIR", action="store", dest="run_dir", default=None)
 

From c51526fe20d8a688372e2d78b454d476dad49cac Mon Sep 17 00:00:00 2001
From: Tim Pillinger <26465611+wxtim@users.noreply.github.com>
Date: Mon, 11 Oct 2021 07:19:47 +0100
Subject: [PATCH 12/14] Apply suggestions from code review

Co-authored-by: Ronnie Dutta <61982285+MetRonnie@users.noreply.github.com>
---
 cylc/flow/scripts/config.py    | 2 +-
 cylc/flow/scripts/install.py   | 4 ++--
 cylc/flow/scripts/subscribe.py | 2 +-
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/cylc/flow/scripts/config.py b/cylc/flow/scripts/config.py
index ca545a18dc1..1a352f56723 100755
--- a/cylc/flow/scripts/config.py
+++ b/cylc/flow/scripts/config.py
@@ -67,7 +67,7 @@
 def get_option_parser():
     parser = COP(
         __doc__,
-        argdoc=[("[WORKFLOW]", "Workflow name or path")],
+        argdoc=[("[WORKFLOW]", "Workflow name, ID, or path")],
         jset=True, icp=True
     )
 
diff --git a/cylc/flow/scripts/install.py b/cylc/flow/scripts/install.py
index aa2e1cc6ba8..f8e41b140d8 100755
--- a/cylc/flow/scripts/install.py
+++ b/cylc/flow/scripts/install.py
@@ -86,7 +86,7 @@
 def get_option_parser():
     parser = COP(
         __doc__, comms=True, prep=True,
-        argdoc=[('[WORKFLOW]', 'Workflow name or ID')]
+        argdoc=[('[WORKFLOW_NAME]', 'Workflow name')]
     )
 
     parser.add_option(
@@ -153,7 +153,7 @@ def install(
         source = opts.source
     else:
         if opts.source:
-            parser.error("WORKFLOW and --directory are mutually exclusive.")
+            parser.error("WORKFLOW_NAME and --directory are mutually exclusive.")
         source = search_install_source_dirs(reg)
     flow_name = opts.flow_name or reg
 
diff --git a/cylc/flow/scripts/subscribe.py b/cylc/flow/scripts/subscribe.py
index a825c46105b..674e79d7a8c 100755
--- a/cylc/flow/scripts/subscribe.py
+++ b/cylc/flow/scripts/subscribe.py
@@ -57,7 +57,7 @@ def get_option_parser():
     parser = COP(
         __doc__,
         argdoc=[
-            ('WORKFLOW', 'Workflow name or ID')
+            ('WORKFLOW_ID', 'Workflow ID')
         ],
         comms=True
     )

From 27bcc5af83fa496d383cf99a25379b16199de4c8 Mon Sep 17 00:00:00 2001
From: Tim Pillinger <26465611+wxtim@users.noreply.github.com>
Date: Mon, 11 Oct 2021 07:38:44 +0100
Subject: [PATCH 13/14] Fixed some review comments; fixed cylc play docstring!

---
 cylc/flow/option_parsers.py                      |  4 ++--
 cylc/flow/scheduler_cli.py                       | 16 +++++++++-------
 cylc/flow/scripts/install.py                     |  3 ++-
 tests/functional/clock-expire/00-basic/flow.cylc |  2 +-
 4 files changed, 14 insertions(+), 11 deletions(-)

diff --git a/cylc/flow/option_parsers.py b/cylc/flow/option_parsers.py
index 4ad2107e08a..15231f79924 100644
--- a/cylc/flow/option_parsers.py
+++ b/cylc/flow/option_parsers.py
@@ -177,9 +177,9 @@ def __init__(
         self.auto_add = auto_add
         if argdoc is None:
             if prep:
-                argdoc = [('WORKFLOW', 'Workflow name or path')]
+                argdoc = [('WORKFLOW | PATH', 'Workflow name or path')]
             else:
-                argdoc = [('REG', 'Workflow name')]
+                argdoc = [('WORKFLOW', 'Workflow name')]
 
         if '--color=never' not in '='.join(sys.argv[2:]):
             # Before option parsing, for `--help`, make comments grey in usage.
diff --git a/cylc/flow/scheduler_cli.py b/cylc/flow/scheduler_cli.py
index 359f88c2053..fc1fedadee3 100644
--- a/cylc/flow/scheduler_cli.py
+++ b/cylc/flow/scheduler_cli.py
@@ -71,16 +71,18 @@
 as satisfied.
 
 Examples:
-    # Start (at the initial cycle point), or restart, or resume workflow REG
-    $ cylc play REG
+    # Start (at the initial cycle point), restart, or resume workflow WORKFLOW
+    $ cylc play WORKFLOW
 
     # Start a new run from a cycle point after the initial cycle point
-    $ cylc play --start-cycle-point=3 REG  # (integer cycling)
-    $ cylc play --start-cycle-point=20250101T0000Z REG  # (datetime cycling)
+    # (integer cycling)
+    $ cylc play --start-cycle-point=3 WORKFLOW
+    # (datetime cycling):
+    $ cylc play --start-cycle-point=20250101T0000Z WORKFLOW
 
     # Start a new run from specified tasks in the graph
-    $ cylc play --start-task=foo.3 REG
-    $ cylc play -t foo.3 -t bar.3 REG
+    $ cylc play --start-task=foo.3 WORKFLOW
+    $ cylc play -t foo.3 -t bar.3 WORKFLOW
 
     # Start, restart or resume the second installed run of the workflow
     # "dogs/fido"
@@ -91,7 +93,7 @@
 """
 
 
-FLOW_NAME_ARG_DOC = ("REG", "Workflow name")
+FLOW_NAME_ARG_DOC = ("WORKFLOW", "Workflow name or ID")
 
 RESUME_MUTATION = '''
 mutation (
diff --git a/cylc/flow/scripts/install.py b/cylc/flow/scripts/install.py
index f8e41b140d8..ea8b65e3c5e 100755
--- a/cylc/flow/scripts/install.py
+++ b/cylc/flow/scripts/install.py
@@ -153,7 +153,8 @@ def install(
         source = opts.source
     else:
         if opts.source:
-            parser.error("WORKFLOW_NAME and --directory are mutually exclusive.")
+            parser.error(
+                "WORKFLOW_NAME and --directory are mutually exclusive.")
         source = search_install_source_dirs(reg)
     flow_name = opts.flow_name or reg
 
diff --git a/tests/functional/clock-expire/00-basic/flow.cylc b/tests/functional/clock-expire/00-basic/flow.cylc
index f36b24ba741..936c078484b 100644
--- a/tests/functional/clock-expire/00-basic/flow.cylc
+++ b/tests/functional/clock-expire/00-basic/flow.cylc
@@ -4,7 +4,7 @@
 Skip a daily post-processing workflow if the 'copy' task has expired."""
 
 [scheduler]
-    cycle point format = %Y-%m-%dT%H
+    # cycle point format = %Y-%m-%dT%H%M
     allow implicit tasks = True
     [[events]]
         abort on stall timeout = True

From b6ff733ebd97f84e1da4afa698b073dd08d3ad66 Mon Sep 17 00:00:00 2001
From: Tim Pillinger <26465611+wxtim@users.noreply.github.com>
Date: Mon, 11 Oct 2021 08:15:13 +0100
Subject: [PATCH 14/14] fix test reliant on REG

---
 tests/functional/cylc-install/00-simple.t | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/tests/functional/cylc-install/00-simple.t b/tests/functional/cylc-install/00-simple.t
index 035d763c382..ddbf44312da 100755
--- a/tests/functional/cylc-install/00-simple.t
+++ b/tests/functional/cylc-install/00-simple.t
@@ -40,23 +40,23 @@ popd || exit 1
 purge_rnd_workflow
 
 # -----------------------------------------------------------------------------
-# Test default name: "cylc install REG" (flow in confgured source dir)
+# Test default name: "cylc install WORKFLOW_NAME" (flow in confgured source dir)
 make_rnd_workflow
 # Before adding workflow to ~/cylc-src/, check install fails:
-TEST_NAME="${TEST_NAME_BASE}-REG-fail-no-src-dir"
+TEST_NAME="${TEST_NAME_BASE}-WORKFLOW_NAME-fail-no-src-dir"
 run_fail "${TEST_NAME}" cylc install "${RND_WORKFLOW_NAME}"
 # Now add workflow to ~/cylc-src/
 RND_WORKFLOW_SOURCE="${PWD}/cylc-src/${RND_WORKFLOW_NAME}"
 mv "$RND_WORKFLOW_NAME" "${PWD}/cylc-src/"
 pushd "${RND_WORKFLOW_SOURCE}" || exit 1
-# Test REG and --directory are mutually exclusive
-TEST_NAME="${TEST_NAME_BASE}-REG-and--directory-forbidden"
+# Test WORKFLOW_NAME and --directory are mutually exclusive
+TEST_NAME="${TEST_NAME_BASE}-WORKFLOW_NAME-and--directory-forbidden"
 run_fail "${TEST_NAME}" cylc install "${RND_WORKFLOW_NAME}" -C "${RND_WORKFLOW_SOURCE}"
 contains_ok "${TEST_NAME}.stderr" <<__ERR__
-cylc: error: REG and --directory are mutually exclusive.
+cylc: error: WORKFLOW_NAME and --directory are mutually exclusive.
 __ERR__
 # Finally test normal case
-TEST_NAME="${TEST_NAME_BASE}-REG-install-ok"
+TEST_NAME="${TEST_NAME_BASE}-WORKFLOW_NAME-install-ok"
 run_ok "${TEST_NAME}" cylc install "${RND_WORKFLOW_NAME}"
 contains_ok "${TEST_NAME}.stdout" <<__OUT__
 INSTALLED $RND_WORKFLOW_NAME/run1 from ${RND_WORKFLOW_SOURCE}