2 files changed, 9 insertions, 2 deletions

diff --git a/DOCS/interface-changes.rst b/DOCS/interface-changes.rst
index 0584409eb9..f3605016a8 100644
--- a/DOCS/interface-changes.rst
+++ b/DOCS/interface-changes.rst
@@ -41,6 +41,8 @@ Interface changes
       support for lavfi filters still has some differences, such as how strings
       are escaped.) If this happens, the non-deprecated builtin filters might be
       moved to "somewhere else" syntax-wise.
+    - deprecate --loop - after a deprecation period, it will be undeprecated,
+      but changed to alias --loop-file
  --- mpv 0.24.0 ---
     - deprecate --hwdec-api and replace it with --opengl-hwdec-interop.
       The new option accepts both --hwdec values, as well as named backends.
diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst
index 1a5bd637b7..ecf8d8ada3 100644
--- a/DOCS/man/options.rst
+++ b/DOCS/man/options.rst
@@ -134,17 +134,22 @@ Playback Control
     speed higher than normal automatically inserts the ``scaletempo`` audio
     filter.
 
-``--loop=<N|inf|force|no>``, ``--loop``
+``--loop-playlist=<N|inf|force|no>``, ``--loop-playlist``
     Loops playback ``N`` times. A value of ``1`` plays it one time (default),
     ``2`` two times, etc. ``inf`` means forever. ``no`` is the same as ``1`` and
     disables looping. If several files are specified on command line, the
-    entire playlist is looped. ``--loop`` is the same as ``--loop=inf``.
+    entire playlist is looped. ``--loop-playlist`` is the same as
+    ``--loop-playlist=inf``.
 
     The ``force`` mode is like ``inf``, but does not skip playlist entries
     which have been marked as failing. This means the player might waste CPU
     time trying to loop a file that doesn't exist. But it might be useful for
     playing webradios under very bad network conditions.
 
+``--loop``
+    Currently a deprecated alias to ``--loop-playlist``. After a deprecation
+    period, it will be undeprecated, but changed to alias ``--loop-file``.
+
 ``--pause``
     Start the player in paused state.