From 50bb12ef4ec09bfa4ac24803681002c3777d5d70 Mon Sep 17 00:00:00 2001
From: Sebastian Cao <cycsmail@gmail.com>
Date: Thu, 6 Aug 2026 10:01:12 +0800
Subject: [PATCH] duplicates: improve the checksum option docs

---
 docs/changelog.rst          | 10 +++++++---
 docs/plugins/duplicates.rst | 29 +++++++++++++++++++++++++----
 2 files changed, 32 insertions(+), 7 deletions(-)

diff --git a/docs/changelog.rst b/docs/changelog.rst
index 4d98aa214f..823cccab43 100644
--- a/docs/changelog.rst
+++ b/docs/changelog.rst
@@ -55,9 +55,13 @@ Bug fixes
     For plugin developers
     ~~~~~~~~~~~~~~~~~~~~~
 
-..
-    Other changes
-    ~~~~~~~~~~~~~
+Other changes
+~~~~~~~~~~~~~
+
+- :doc:`plugins/duplicates`: Improve the documentation of the ``checksum``
+  option: explain how the external command is run, remove the broken ``md5sum
+  {file}`` example and show how to use such commands through a wrapper script.
+  :bug:`3979`
 
 2.13.1 (July 29, 2026)
 ----------------------
diff --git a/docs/plugins/duplicates.rst b/docs/plugins/duplicates.rst
index ed94975e95..ce64493db6 100644
--- a/docs/plugins/duplicates.rst
+++ b/docs/plugins/duplicates.rst
@@ -47,8 +47,14 @@ file. The available options mirror the command-line options:
   overrides the ``keys`` option the first time it is run; however, because it
   caches the resulting checksum as ``flexattrs`` in the database, you can use
   ``--key=name_of_the_checksumming_program --key=any_other_keys`` (or set the
-  ``keys`` configuration option) the second time around. Default: ``ffmpeg -i
-  {file} -f crc -``.
+  ``keys`` configuration option) the second time around. The command is not run
+  through a shell: it is split into arguments (respecting shell-like quoting)
+  and ``{file}`` is then replaced with the item's path within each argument, so
+  paths containing spaces need no extra quoting, but shell features such as
+  pipes or redirection cannot be used. The command's entire output is used as
+  the checksum, so it must not contain anything that differs between copies of
+  the same file, such as the file's path. Default: ``ffmpeg -i {file} -f crc
+  -``.
 - **copy**: A destination base directory into which to copy matched items.
   Default: none (disabled).
 - **count**: Print a count of duplicate tracks or albums in the format
@@ -126,13 +132,28 @@ Get tracks with the same title, artist, and album:
 
     beet duplicates -k title -k albumartist -k album
 
-Compute Adler CRC32 or MD5 checksums, storing them as flexattrs, and report back
+Compute Adler CRC32 checksums, storing them as flexattrs, and report back
 duplicates based on those values:
 
 ::
 
     beet dup -C 'ffmpeg -i {file} -f crc -'
-    beet dup -C 'md5sum {file}'
+
+Note that ``beet dup -C 'md5sum {file}'`` would not work: the command's entire
+output is used as the checksum, and ``md5sum`` prints the file's path after the
+hash, so copies of the same file at different paths would never match. Instead,
+wrap the command in a script that prints only the hash:
+
+::
+
+    #!/bin/sh
+    md5sum "$1" | awk '{print $1}'
+
+and use that script as the checksum command:
+
+::
+
+    beet dup -C 'myscript {file}'
 
 Copy highly danceable items to ``party`` directory: