Update documentation for cmd tasks

docs/tasks/task_types/cmd.rst

@@ -1,8 +1,7 @@
 ``cmd`` tasks
 =============
 
-**Command tasks** contain a single command that will be executed as a sub process without a shell.
-This covers most basic use cases such as the following examples.
+**Command tasks** contain a single command that will be executed as a sub-process without a shell. This covers most basic use cases such as the following examples.
 
 .. code-block:: toml
 
@@ -13,6 +12,7 @@ This covers most basic use cases such as the following examples.
 
   Tasks defined as just a string value, are interpreted as ``cmd`` tasks by default.
 
+
 Available task options
 ----------------------
 
@@ -22,14 +22,14 @@ Available task options
 Shell like features
 -------------------
 
-It it important to understand that ``cmd`` tasks are executed without a shell (to maximise portability). However some shell like features are still available.
+It is important to understand that ``cmd`` tasks are executed without a shell (to maximise portability). However some shell like features are still available including basic parameter expansion and pattern matching. Quotes and escapes are also generally interpreted as one would expect in a shell.
 
 .. _ref_env_vars:
 
 Referencing environment variables
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Environment variables can be referenced using shell like syntax and are templated into the command.
+Environment variables can be templated into the command. Just like in bash: whitespace inside a variable results in a word break, and glob patterns are evaluated after parameter expansion, unless the parameter expansion is inside double quotes. Single quotes disable parameter expansion. Curly braces are recommended but optional.
 
 .. code-block:: toml
 
@@ -42,19 +42,22 @@ Environment variables can be referenced using shell like syntax and are template
   Poe => echo Hello nat
   Hello nat
 
-Parsing of variable referenced can be ignored by escaping with a backslash like so:
-
+Parameter expansion can also can be disabled by escaping the $ with a backslash like so:
 
 .. code-block:: toml
 
   [tool.poe.tasks]
-  greet = "echo Hello \\${USER}"  # the backslash itself needs escaping for the toml parser
+  greet = "echo Hello \\$USER"  # the backslash itself needs escaping for the toml parser
 
 
 Glob expansion
 ~~~~~~~~~~~~~~
 
-Glob patterns in cmd tasks are expanded and replaced with their results.
+Glob patterns in cmd tasks are expanded and replaced with the list of matching files and directories. The supported glob syntax is that of the |glob_link|, which differs from bash in that square bracket patterns don't support character classes, don't break on whitespace, and don't allow escaping of contained characters.
+
+Glob patterns are evaluated relative to the working directory of the task, and if there are no matches then the pattern is expanded to nothing.
+
+Here's an example of task using a recursive glob pattern:
 
 .. code-block:: toml
 
@@ -71,8 +74,13 @@ Glob patterns in cmd tasks are expanded and replaced with their results.
 
 .. seealso::
 
-  Notice that this example also demonstrates that comments and excess whitespace (including new lines) are ignored.
+  Notice that this example also demonstrates that comments and excess whitespace (including new lines) are ignored, without needing to escape new lines.
 
 .. seealso::
 
-  Much like in a POSIX shell, the glob pattern can be escaped by wrapping it in single quotes.
+  Much like in bash, the glob pattern can be escaped by wrapping it in quotes, or preceding it with a backslash.
+
+
+.. |glob_link| raw:: html
+
+   <a href="https://docs.python.org/3/library/glob.html" target="_blank">python standard library glob module</a>

pyproject.toml

@@ -7,7 +7,7 @@ readme        = "README.md"
 license       = "MIT"
 repository    = "https://github.com/nat-n/poethepoet"
 homepage      = "https://github.com/nat-n/poethepoet"
-documentation = "http://poethepoet.natn.io/"
+documentation = "https://poethepoet.natn.io/"
 keywords      = ["automation", "tasks", "task-runner", "plugin", "poetry", "poe"]
 classifiers   = ["Topic :: Software Development :: Build Tools"]
 

tests/helpers/command/test_ast.py

@@ -245,11 +245,12 @@ def test_parse_globs():
         a*b?c[]xyz\\ ]d[!]][!] ]
         "a*b?c[]xyz\\ ]d[!]][!] ]"
         'a*b?c[]xyz\\ ]d[!]][!] ]'
+        a\\*b\\?c\\[]xyz\\\\\\ ]d\\[!]]\\[!]\\ ]
         """,
         config=ParseConfig(),
     )
     print(tree.pretty())
-    assert len(tree.lines) == 4
+    assert len(tree.lines) == 5
     assert tree.lines[0] == (
         (("*",),),
         (("?",),),
@@ -264,6 +265,7 @@ def test_parse_globs():
     )
     assert tree.lines[2] == ((("a*b?c[]xyz\\ ]d[!]][!] ]",),),)
     assert tree.lines[3] == ((("a*b?c[]xyz\\ ]d[!]][!] ]",),),)
+    assert tree.lines[4] == ((("a*b?c[]xyz\\ ]d[!]][!] ]",),),)
 
 
 def test_parse_non_globs():