Document the clean_stagedir config and cmd option

Plus a minor fix in the implementation along with unit test adaptation.

Author: Vasileios Karakasis

docs/config_reference.rst

@@ -1037,6 +1037,16 @@ General Configuration
 
 
 
+.. js:attribute:: .general[].clean_stagedir
+
+   :required: No
+   :default: ``true``
+
+   Clean stage directory of tests before populating it.
+
+   .. versionadded:: 3.1
+
+
 .. js:attribute:: .general[].colorize
 
    :required: No

docs/manpage.rst

@@ -219,6 +219,14 @@ Options controlling ReFrame output
 
    This option can also be set using the :envvar:`RFM_KEEP_STAGE_FILES` environment variable or the :js:attr:`keep_stage_files` general configuration parameter.
 
+.. option:: --dont-restage
+
+   Do not restage a test if its stage directory exists.
+   Normally, if the stage directory of a test exists, ReFrame will remove it and recreate it.
+   This option disables this behavior.
+
+   .. versionadded:: 3.1
+
 .. option:: --save-log-files
 
    Save ReFrame log files in the output directory before exiting.
@@ -585,6 +593,21 @@ Here is an alphabetical list of the environment variables recognized by ReFrame:
       ================================== ==================
 
 
+.. envvar:: RFM_CLEAN_STAGEDIR
+
+   Clean stage directory of tests before populating it.
+
+   .. versionadded:: 3.1
+
+   .. table::
+      :align: left
+
+      ================================== ==================
+      Associated command line option     :option:`--dont-restage`
+      Associated configuration parameter :js:attr:`clean_stagedir` general configuration parameter
+      ================================== ==================
+
+
 .. envvar:: RFM_COLORIZE
 
    Enable output coloring.

reframe/utility/os_ext.py

@@ -124,8 +124,9 @@ def copytree(src, dst, symlinks=False, ignore=None, copy_function=shutil.copy2,
 
     for d in subdirs:
         if d not in ignore_paths:
-            copytree(os.path.join(src, d), os.path.join(dst, d), symlinks,
-                     ignore, copy_function, ignore_dangling_symlinks)
+            copytree(os.path.join(src, d), os.path.join(dst, d),
+                     symlinks, ignore, copy_function,
+                     ignore_dangling_symlinks, dirs_exist_ok)
 
     return dst
 

unittests/test_utility.py

@@ -276,6 +276,9 @@ def setUp(self):
         open(os.path.join(self.prefix, 'bar.txt'), 'w').close()
         open(os.path.join(self.prefix, 'foo.txt'), 'w').close()
 
+        # Create also a subdirectory in target, so as to check the recursion
+        os.makedirs(os.path.join(self.target, 'foo'), exist_ok=True)
+
     def verify_target_directory(self, file_links=[]):
         '''Verify the directory structure'''
         assert os.path.exists(os.path.join(self.target, 'bar', 'bar.txt'))
@@ -296,6 +299,10 @@ def test_virtual_copy_nolinks(self):
         os_ext.copytree_virtual(self.prefix, self.target, dirs_exist_ok=True)
         self.verify_target_directory()
 
+    def test_virtual_copy_nolinks_dirs_exist(self):
+        with pytest.raises(FileExistsError):
+            os_ext.copytree_virtual(self.prefix, self.target)
+
     def test_virtual_copy_valid_links(self):
         file_links = ['bar/', 'foo/bar.txt', 'foo.txt']
         os_ext.copytree_virtual(self.prefix, self.target,