fix: write out .gitignore/CACHEDIR.TAG to our dir (#1072)

* chore: write out gitignore to our dir

Signed-off-by: Henry Schreiner <henryfs@princeton.edu>

* Update nox/virtualenv.py

* chore: also CACHEDIR.TAG

Signed-off-by: Henry Schreiner <henryfs@princeton.edu>

* tests: add some tests

Signed-off-by: Henry Schreiner <henryfs@princeton.edu>

* fix: address feedback

Signed-off-by: Henry Schreiner <henryfs@princeton.edu>

---------

Signed-off-by: Henry Schreiner <henryfs@princeton.edu>

Author: henryiii

.gitignore

@@ -1,5 +1,6 @@
 .mypy_cache/
 .vscode/
+.DS_Store
 
 # Byte-compiled / optimized / DLL files
 __pycache__/

nox/virtualenv.py

@@ -242,6 +242,36 @@ def pbs_install_python(python_version: str) -> str | None:
 HAS_UV, UV, UV_VERSION = find_uv()
 
 
+def _ensure_gitignore(envdir: Path) -> None:
+    """Ensure the shared environment directory has a broad gitignore."""
+    envdir.mkdir(parents=True, exist_ok=True)
+
+    gitignore = envdir.joinpath(".gitignore")
+    if gitignore.exists():
+        return
+
+    try:
+        gitignore.write_text("*\n", encoding="utf-8")
+    except OSError:  # pragma: no cover
+        logger.debug(f"Failed to write {gitignore!s}")
+
+
+def _ensure_cachedir_tag(envdir: Path) -> None:
+    """Ensure the shared environment directory has a CACHEDIR.TAG"""
+    envdir.mkdir(parents=True, exist_ok=True)
+
+    cachedir_tag = envdir.joinpath("CACHEDIR.TAG")
+    if cachedir_tag.exists():
+        return
+
+    try:
+        cachedir_tag.write_text(
+            "Signature: 8a477f597d28d172789f06886806bc55\n", encoding="utf-8"
+        )
+    except OSError:  # pragma: no cover
+        logger.debug(f"Failed to write {cachedir_tag!s}")
+
+
 class InterpreterNotFound(OSError):
     def __init__(self, interpreter: str) -> None:
         super().__init__(f"Python interpreter {interpreter} not found")
@@ -313,9 +343,11 @@ def _get_env(
         if include_outer_env:
             computed_env = {**os.environ, **computed_env}
         if self.bin_paths:
-            computed_env["PATH"] = os.pathsep.join(
-                [*self.bin_paths, computed_env.get("PATH") or ""]
-            )
+            path_parts = [*self.bin_paths]
+            prior_path = computed_env.get("PATH")
+            if prior_path:
+                path_parts.append(prior_path)
+            computed_env["PATH"] = os.pathsep.join(path_parts)
         return computed_env
 
 
@@ -494,6 +526,10 @@ def bin_paths(self) -> list[str]:
 
     def create(self) -> bool:
         """Create the conda env."""
+        nox_dir = Path(self.location).parent
+        _ensure_gitignore(nox_dir)
+        _ensure_cachedir_tag(nox_dir)
+
         if not self._clean_location():
             logger.debug(f"Reusing existing conda env at {self.location_name}.")
 
@@ -797,6 +833,10 @@ def bin_paths(self) -> list[str]:
 
     def create(self) -> bool:
         """Create the virtualenv or venv."""
+        nox_dir = Path(self.location).parent
+        _ensure_gitignore(nox_dir)
+        _ensure_cachedir_tag(nox_dir)
+
         if not self._clean_location():
             logger.debug(
                 f"Reusing existing virtual environment at {self.location_name}."

tests/test_virtualenv.py

@@ -142,6 +142,64 @@ def test_process_env_create() -> None:
         nox.virtualenv.ProcessEnv()  # type: ignore[abstract]
 
 
+def test_process_env_get_env_with_bin_paths() -> None:
+    penv = nox.virtualenv.PassthroughEnv(bin_paths=["/test/bin"])
+    env = penv._get_env({})
+    path = env.get("PATH")
+    assert path
+    assert "/test/bin" in path
+
+
+def test_process_env_get_env_exclude_outer() -> None:
+    penv = nox.virtualenv.PassthroughEnv(bin_paths=["/test/bin"], env={"TEST": "value"})
+    env = penv._get_env({}, include_outer_env=False)
+    assert env["TEST"] == "value"
+    assert env["PATH"] == "/test/bin"
+
+
+def test_ensure_gitignore_creates_file(tmp_path: Path) -> None:
+    envdir = tmp_path.joinpath(".nox")
+    location = envdir.joinpath("session")
+
+    nox.virtualenv._ensure_gitignore(location.parent)
+
+    assert envdir.joinpath(".gitignore").read_text(encoding="utf-8") == "*\n"
+
+
+def test_ensure_cachedir_tag_creates_file(tmp_path: Path) -> None:
+    envdir = tmp_path.joinpath(".nox")
+    location = envdir.joinpath("session")
+
+    nox.virtualenv._ensure_cachedir_tag(location.parent)
+
+    assert (
+        envdir.joinpath("CACHEDIR.TAG").read_text(encoding="utf-8")
+        == "Signature: 8a477f597d28d172789f06886806bc55\n"
+    )
+
+
+def test_ensure_parent_gitignore_keeps_existing_file(tmp_path: Path) -> None:
+    envdir = tmp_path.joinpath(".nox")
+    envdir.mkdir()
+    gitignore = envdir.joinpath(".gitignore")
+    gitignore.write_text("!keep\n", encoding="utf-8")
+
+    nox.virtualenv._ensure_gitignore(envdir)
+
+    assert gitignore.read_text(encoding="utf-8") == "!keep\n"
+
+
+def test_ensure_parent_cachedir_tag_keeps_existing_file(tmp_path: Path) -> None:
+    envdir = tmp_path.joinpath(".nox")
+    envdir.mkdir()
+    cachedir_tag = envdir.joinpath("CACHEDIR.TAG")
+    cachedir_tag.write_text("!keep\n", encoding="utf-8")
+
+    nox.virtualenv._ensure_cachedir_tag(envdir)
+
+    assert cachedir_tag.read_text(encoding="utf-8") == "!keep\n"
+
+
 def test_invalid_venv_create(
     make_one: Callable[
         ..., tuple[nox.virtualenv.VirtualEnv | nox.virtualenv.ProcessEnv, Path]
@@ -151,6 +209,100 @@ def test_invalid_venv_create(
         make_one(venv_backend="invalid")
 
 
+def test_get_virtualenv_invalid_backend(
+    tmp_path: Path,
+) -> None:
+    with pytest.raises(ValueError, match="Expected venv_backend one of"):
+        nox.virtualenv.get_virtualenv(
+            "invalid",
+            download_python="auto",
+            envdir=str(tmp_path),
+            reuse_existing=False,
+        )
+
+
+def test_get_virtualenv_fallback_to_available_backend(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    # Force optional backends to be unavailable so fallback behavior is deterministic.
+    monkeypatch.setattr(
+        nox.virtualenv,
+        "OPTIONAL_VENVS",
+        {"conda": False, "mamba": False, "micromamba": False, "uv": False},
+    )
+    venv = nox.virtualenv.get_virtualenv(
+        "conda",
+        "mamba",
+        "venv",
+        download_python="auto",
+        envdir=str(tmp_path),
+        reuse_existing=False,
+    )
+    assert isinstance(venv, nox.virtualenv.VirtualEnv)
+    assert venv.venv_backend == "venv"
+
+
+def test_get_virtualenv_no_backends_available(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    # Simulate no optional backends present.
+    monkeypatch.setattr(
+        nox.virtualenv,
+        "OPTIONAL_VENVS",
+        {"conda": False, "mamba": False, "micromamba": False, "uv": False},
+    )
+    with pytest.raises(ValueError, match="No backends present"):
+        nox.virtualenv.get_virtualenv(
+            "conda",
+            "mamba",
+            download_python="auto",
+            envdir=str(tmp_path),
+            reuse_existing=False,
+        )
+
+
+def test_get_virtualenv_none_backend(
+    tmp_path: Path,
+) -> None:
+    venv = nox.virtualenv.get_virtualenv(
+        "none",
+        download_python="auto",
+        envdir=str(tmp_path),
+        reuse_existing=False,
+    )
+    assert isinstance(venv, nox.virtualenv.ProcessEnv)
+
+
+def test_get_virtualenv_interpreter_false(
+    tmp_path: Path,
+) -> None:
+    venv = nox.virtualenv.get_virtualenv(
+        "venv",
+        download_python="auto",
+        envdir=str(tmp_path),
+        reuse_existing=False,
+        interpreter=False,
+    )
+    assert isinstance(venv, nox.virtualenv.ProcessEnv)
+
+
+def test_get_virtualenv_non_optional_fallback(
+    tmp_path: Path,
+) -> None:
+    with pytest.raises(
+        ValueError, match=r"Only optional backends.*may have a fallback"
+    ):
+        nox.virtualenv.get_virtualenv(
+            "venv",
+            "uv",
+            download_python="auto",
+            envdir=str(tmp_path),
+            reuse_existing=False,
+        )
+
+
 def test_condaenv_constructor_defaults(
     make_conda: Callable[..., tuple[CondaEnv, Path]],
 ) -> None: