feat: add --fresh flag to recreate environments from scratch

src/hatch/cli/application.py

@@ -48,8 +48,8 @@ def config(self) -> RootConfig:
     def get_environment(self, env_name: str | None = None) -> EnvironmentInterface:
         return self.project.get_environment(env_name)
 
-    def prepare_environment(self, environment: EnvironmentInterface, *, keep_env: bool = False):
-        self.project.prepare_environment(environment, keep_env=keep_env)
+    def prepare_environment(self, environment: EnvironmentInterface, *, keep_env: bool = False, fresh: bool = False):
+        self.project.prepare_environment(environment, keep_env=keep_env, fresh=fresh)
 
     def run_shell_commands(self, context: ExecutionContext) -> None:
         with context.env.command_context():
@@ -106,6 +106,7 @@ def runner_context(
         ignore_compat: bool = False,
         display_header: bool = False,
         keep_env: bool = False,
+        fresh: bool = False,
     ) -> Generator[ExecutionContext, None, None]:
         if self.verbose or len(environments) > 1:
             display_header = True
@@ -132,7 +133,7 @@ def runner_context(
                 context = ExecutionContext(environment)
                 yield context
 
-                self.prepare_environment(environment, keep_env=keep_env)
+                self.prepare_environment(environment, keep_env=keep_env, fresh=fresh)
                 self.execute_context(context)
 
         if incompatible:

src/hatch/cli/env/run.py

@@ -33,6 +33,11 @@ def filter_environments(environments, filter_data):
     "--force-continue", is_flag=True, help="Run every command and if there were any errors exit with the first code"
 )
 @click.option("--ignore-compat", is_flag=True, help="Ignore incompatibility when selecting specific environments")
+@click.option(
+    "--fresh",
+    is_flag=True,
+    help="Create a fresh environment for each run, removing the existing one first",
+)
 @click.pass_obj
 def run(
     app: Application,
@@ -44,6 +49,7 @@ def run(
     filter_json: str | None,
     force_continue: bool,
     ignore_compat: bool,
+    fresh: bool,
 ):
     """
     Run commands within project environments.
@@ -139,6 +145,7 @@ def run(
         ignore_compat=ignore_compat or matrix_selected,
         display_header=matrix_selected,
         keep_env=bool(os.environ.get(AppEnvVars.KEEP_ENV)),
+        fresh=fresh or bool(os.environ.get(AppEnvVars.FRESH)),
     ):
         if context.env.name == "system":
             context.env.exists = lambda: True  # type: ignore[method-assign]

src/hatch/config/constants.py

@@ -10,6 +10,7 @@ class AppEnvVars:
     NO_COLOR = "NO_COLOR"
     FORCE_COLOR = "FORCE_COLOR"
     KEEP_ENV = "HATCH_KEEP_ENV"
+    FRESH = "HATCH_FRESH"
 
 
 class ConfigEnvVars:

src/hatch/project/core.py

@@ -194,7 +194,11 @@ def managed_environment(
 
     # Ensure that this method is clearly written since it is
     # used for documenting the life cycle of environments.
-    def prepare_environment(self, environment: EnvironmentInterface, *, keep_env: bool):
+    def prepare_environment(self, environment: EnvironmentInterface, *, keep_env: bool, fresh: bool = False):
+        if fresh and environment.exists():
+            environment.remove()
+            self.env_metadata.reset(environment)
+
         if not environment.exists():
             with self.managed_environment(environment, keep_env=keep_env):
                 self.env_metadata.reset(environment)

tests/cli/env/test_run.py

@@ -306,3 +306,50 @@ def test_plugin_dependencies_unmet(hatch, helpers, temp_dir, config_file, mock_p
     assert env_path.name == project_path.name
 
     assert str(env_path) in str(output_file.read_text())
+
+def test_fresh(hatch, helpers, temp_dir, config_file):
+    config_file.model.template.plugins["default"]["tests"] = False
+    config_file.save()
+
+    project_name = "My.App"
+
+    with temp_dir.as_cwd():
+        result = hatch("new", project_name)
+
+    assert result.exit_code == 0, result.output
+
+    project_path = temp_dir / "my-app"
+    data_path = temp_dir / "data"
+    data_path.mkdir()
+
+    project = Project(project_path)
+    helpers.update_project_environment(
+        project,
+        "default",
+        {"skip-install": True, **project.config.envs["default"]},
+    )
+
+    with project_path.as_cwd(env_vars={ConfigEnvVars.DATA: str(data_path)}):
+        result = hatch("env", "run", "--", "python", "-c", "import sys;sys.exit(0)")
+
+    assert result.exit_code == 0, result.output
+    assert "Creating environment" in result.output
+
+    env_data_path = data_path / "env" / "virtual" / project_path.name
+    storage_dirs = list(env_data_path.iterdir())
+    assert len(storage_dirs) == 1
+    storage_path = storage_dirs[0]
+    env_dirs_before = list(storage_path.iterdir())
+    assert len(env_dirs_before) == 1
+    env_path_before = env_dirs_before[0]
+    assert env_path_before.is_dir()
+
+    with project_path.as_cwd(env_vars={ConfigEnvVars.DATA: str(data_path)}):
+        result = hatch("env", "run", "--fresh", "--", "python", "-c", "import sys;sys.exit(0)")
+
+    assert result.exit_code == 0, result.output
+
+    env_dirs_after = list(storage_path.iterdir())
+    assert len(env_dirs_after) == 1
+    env_path_after = env_dirs_after[0]
+    assert env_path_after.is_dir()