Ensure tox-created directories contain CACHEDIR.TAG

Fixes #3334

Author: akx

docs/changelog/3342.feature.rst

@@ -0,0 +1,3 @@
+Tox now creates ``CACHEDIR.TAG`` files in the workdir subdirectories it creates, so that tools like ``tar``
+can exclude them from e.g. backups where ephemeral directories are not desired.
+- by :user:`akx`

src/tox/tox_env/api.py

@@ -17,7 +17,7 @@
 from tox.execute.request import ExecuteRequest
 from tox.tox_env.errors import Fail, Recreate, Skip
 from tox.tox_env.info import Info
-from tox.util.path import ensure_empty_dir
+from tox.util.path import ensure_cachedir_dir, ensure_empty_dir
 
 if TYPE_CHECKING:
     from tox.config.cli.parser import Parsed
@@ -314,7 +314,7 @@ def _handle_env_tmp_dir(self) -> None:
         env_tmp_dir.mkdir(parents=True, exist_ok=True)
 
     def _handle_core_tmp_dir(self) -> None:
-        self.core["temp_dir"].mkdir(parents=True, exist_ok=True)
+        ensure_cachedir_dir(self.core["temp_dir"])
 
     def _clean(self, transitive: bool = False) -> None:  # noqa: ARG002, FBT001, FBT002
         if self._run_state["clean"]:  # pragma: no branch

src/tox/tox_env/info.py

@@ -9,6 +9,8 @@
 from contextlib import contextmanager
 from typing import TYPE_CHECKING, Any, Iterator
 
+from tox.util.path import ensure_cachedir_dir
+
 if TYPE_CHECKING:
     from pathlib import Path
 
@@ -63,7 +65,7 @@ def reset(self) -> None:
         self._content = {}
 
     def _write(self) -> None:
-        self._path.parent.mkdir(parents=True, exist_ok=True)
+        ensure_cachedir_dir(self._path.parent)
         self._path.write_text(json.dumps(self._content, indent=2))
 
 

src/tox/tox_env/package.py

@@ -10,6 +10,8 @@
 
 from filelock import FileLock
 
+from tox.util.path import ensure_cachedir_dir
+
 from .api import ToxEnv, ToxEnvCreateArgs
 
 if TYPE_CHECKING:
@@ -69,7 +71,7 @@ def register_config(self) -> None:
         super().register_config()
         file_lock_path: Path = self.conf["env_dir"] / "file.lock"
         self._file_lock = FileLock(file_lock_path)
-        file_lock_path.parent.mkdir(parents=True, exist_ok=True)
+        ensure_cachedir_dir(file_lock_path.parent)
         self.core.add_config(
             keys=["package_root", "setupdir"],
             of_type=Path,

src/tox/util/path.py

@@ -7,6 +7,13 @@
     from pathlib import Path
 
 
+CACHEDIR_TAG_CONTENT = b"""Signature: 8a477f597d28d172789f06886806bc55
+# This file is a cache directory tag created by the Tox automation project (https://tox.wiki/).
+# For information about cache directory tags, see:
+#	http://www.brynosaurus.com/cachedir/
+"""
+
+
 def ensure_empty_dir(path: Path, except_filename: str | None = None) -> None:
     if path.exists():
         if path.is_dir():
@@ -24,6 +31,18 @@ def ensure_empty_dir(path: Path, except_filename: str | None = None) -> None:
         path.mkdir(parents=True)
 
 
+def ensure_cachedir_dir(path: Path) -> None:
+    """
+    Ensure that the given path is a directory, exists and
+    contains a `CACHEDIR.TAG` file.
+    """
+    path.mkdir(parents=True, exist_ok=True)
+    cachetag = path / "CACHEDIR.TAG"
+    if not cachetag.is_file():
+        cachetag.write_bytes(CACHEDIR_TAG_CONTENT)
+
+
 __all__ = [
+    "ensure_cachedir_dir",
     "ensure_empty_dir",
 ]