From 6a256606c65e716b9457c50d700d93eaf2b383ca Mon Sep 17 00:00:00 2001
From: Matthew Hughes <matthewhughes934@gmail.com>
Date: Sat, 14 Nov 2020 21:46:40 +0000
Subject: [PATCH] Docs: Note lifetime of temporary directories

Explanation: The default handling of these lifetimes is done in
`tmpdir.TempPathFactory.getbasetemp`, which passes `keep=3` to
`pathlib.make_numbered_dir_with_cleanup`.

GH Issue: #8036
---
 src/_pytest/tmpdir.py | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/src/_pytest/tmpdir.py b/src/_pytest/tmpdir.py
index 4ca1dd6e136..52fc8164241 100644
--- a/src/_pytest/tmpdir.py
+++ b/src/_pytest/tmpdir.py
@@ -174,6 +174,11 @@ def tmpdir(tmp_path: Path) -> py.path.local:
     function invocation, created as a sub directory of the base temporary
     directory.
 
+    By default, a new base temporary directory is created each test session,
+    and old bases are removed after 3 sessions, to aid in debugging. If
+    ``--basetemp`` is used then it is cleared each session. See :ref:`base
+    temporary directory`.
+
     The returned object is a `py.path.local`_ path object.
 
     .. _`py.path.local`: https://py.readthedocs.io/en/latest/path.html
@@ -187,6 +192,11 @@ def tmp_path(request: FixtureRequest, tmp_path_factory: TempPathFactory) -> Path
     function invocation, created as a sub directory of the base temporary
     directory.
 
+    By default, a new base temporary directory is created each test session,
+    and old bases are removed after 3 sessions, to aid in debugging. If
+    ``--basetemp`` is used then it is cleared each session. See :ref:`base
+    temporary directory`.
+
     The returned object is a :class:`pathlib.Path` object.
     """