Document necessity to escape # sign used in commands

... `commands_pre` or `commands_post`.

This fixes #2617.

docs/changelog/2617.doc.rst

@@ -0,0 +1 @@
+Document necessity to escape ``#`` used  in ``commands``, ``commands_pre`` or ``commands_post`` - by :user:`jugmac00`.

docs/config.rst

@@ -409,6 +409,11 @@ Run
    Commands to run before running the :ref:`commands`. All evaluation and configuration logic applies from
    :ref:`commands`.
 
+   .. note::
+
+     When you use the ``#`` sign inside ``commands_pre``, you need to escape it, e.g.
+     ``commands_pre = bash -c "echo 'foo\#bar'"``.
+
 .. conf::
    :keys: commands
    :default: <empty list>
@@ -437,13 +442,23 @@ Run
      ``path/to/my_script`` prefer ``{tox_root}{/}path{/}to{/}my_script``. If your inline script is platform dependent
      refer to :ref:`platform-specification` on how to select different script per platform.
 
+   .. note::
+
+     When you use the ``#`` sign inside ``commands``, you need to escape it, e.g.
+     ``commands = bash -c "echo 'foo\#bar'"``.
+
 .. conf::
    :keys: commands_post
    :default: <empty list>
 
    Commands to run after running the :ref:`commands`. Execute regardless of the outcome of both :ref:`commands` and
    :ref:`commands_pre`. All evaluation and configuration logic applies from :ref:`commands`.
 
+   .. note::
+
+     When you use the ``#`` sign inside ``commands_post``, you need to escape it, e.g.
+     ``commands_post = bash -c "echo 'foo\#bar'"``.
+
 .. conf::
    :keys: change_dir, changedir
    :default: {tox root}

docs/faq.rst

@@ -42,6 +42,23 @@ tox 4 - removed tox.ini keys
 | ``isolated_build``       | Isolated builds are now always used.        |
 +--------------------------+---------------------------------------------+
 
+tox 4 - changed behaviour for tox.ini keys
+++++++++++++++++++++++++++++++++++++++++++
+
+- When using any of the ``commands``, ``commands_pre`` or ``commands_post`` keys, you need to escape the ``#`` sign.
+
+Valid in tox 3:
+
+.. code-block:: ini
+
+  commands = bash -c "echo 'foo#bar'"
+
+Valid in tox 4:
+
+.. code-block:: ini
+
+  commands = bash -c "echo 'foo\#bar'"
+
 tox 4 - substitutions removed
 +++++++++++++++++++++++++++++
 - The ``distshare`` substitution has been removed.