diff --git a/docs/docsite/rst/user_guide/intro_patterns.rst b/docs/docsite/rst/user_guide/intro_patterns.rst
index b3a219486bd..46bd2fc366a 100644
--- a/docs/docsite/rst/user_guide/intro_patterns.rst
+++ b/docs/docsite/rst/user_guide/intro_patterns.rst
@@ -153,6 +153,10 @@ Finally, you can use ``--limit`` to read the list of hosts from a file by prefix
 
     ansible-playbook site.yml --limit @retry_hosts.txt
 
+If :ref:`RETRY_FILES_ENABLED` is set to ``True``, a ``.retry`` file will be created after the ``ansible-playbook`` run containing a list of failed hosts from all plays. This file is overwritten each time ``ansible-playook`` finishes running.
+
+    ansible-playbook site.yml --limit @site.retry
+
 To apply your knowledge of patterns with Ansible commands and playbooks, read :ref:`intro_adhoc` and :ref:`playbooks_intro`.
 
 .. seealso::
diff --git a/lib/ansible/config/base.yml b/lib/ansible/config/base.yml
index fb7bcb261df..90456bbcb40 100644
--- a/lib/ansible/config/base.yml
+++ b/lib/ansible/config/base.yml
@@ -1754,7 +1754,9 @@ RETRY_FILES_ENABLED:
 RETRY_FILES_SAVE_PATH:
   name: Retry files path
   default: ~
-  description: This sets the path in which Ansible will save .retry files when a playbook fails and retry files are enabled.
+  description:
+    - This sets the path in which Ansible will save .retry files when a playbook fails and retry files are enabled.
+    - This file will be overwritten after each run with the list of failed hosts from all plays.
   env: [{name: ANSIBLE_RETRY_FILES_SAVE_PATH}]
   ini:
   - {key: retry_files_save_path, section: defaults}