Document the %sunique template

3 files changed, 33 insertions, 0 deletions

diff --git a/docs/changelog.rst b/docs/changelog.rst
index 31861af24..d21a55d37 100644
--- a/docs/changelog.rst
+++ b/docs/changelog.rst
@@ -35,6 +35,8 @@ New features:
 * :ref:`import-options`: Add support for re-running the importer on paths in
   log files that were created with the ``-l`` (or ``--logfile``) argument.
   :bug:`4379` :bug:`4387`
+* Add :ref:`%sunique{} <sunique>` template to disambiguate between singletons.
+  :bug:`4438`
 
 Bug fixes:
 
diff --git a/docs/reference/config.rst b/docs/reference/config.rst
index 6e7df1b59..58656256f 100644
--- a/docs/reference/config.rst
+++ b/docs/reference/config.rst
@@ -326,6 +326,23 @@ The defaults look like this::
 
 See :ref:`aunique` for more details.
 
+.. _config-sunique:
+
+sunique
+~~~~~~~
+
+These options are used to generate a string that is guaranteed to be unique
+among all singletons in the library who share the same set of keys.
+
+The defaults look like this::
+
+    sunique:
+        keys: artist title
+        disambiguators: year trackdisambig
+        bracket: '[]'
+
+See :ref:`sunique` for more details.
+
 
 .. _terminal_encoding:
 
diff --git a/docs/reference/pathformat.rst b/docs/reference/pathformat.rst
index f6f2e06cc..b52c2b32a 100644
--- a/docs/reference/pathformat.rst
+++ b/docs/reference/pathformat.rst
@@ -73,6 +73,8 @@ These functions are built in to beets:
   option.
 * ``%aunique{identifiers,disambiguators,brackets}``: Provides a unique string
   to disambiguate similar albums in the database. See :ref:`aunique`, below.
+* ``%sunique{identifiers,disambiguators,brackets}``: Provides a unique string
+  to disambiguate similar singletons in the database. See :ref:`sunique`, below.
 * ``%time{date_time,format}``: Return the date and time in any format accepted
   by `strftime`_. For example, to get the year some music was added to your
   library, use ``%time{$added,%Y}``.
@@ -145,6 +147,18 @@ its import time. Only the second album will receive a disambiguation string. If
 you want to add the disambiguation string to both albums, just run ``beet move``
 (possibly restricted by a query) to update the paths for the albums.
 
+.. _sunique:
+
+Singleton Disambiguation
+------------------------
+
+It is also possible to have singleton tracks with the same name and the same
+artist. Beets provides the ``%sunique{}`` template to avoid having the same
+file path.
+
+It has the same arguments as the :ref:`%aunique <aunique>` template, but the default
+values are different. The default identifiers are ``artist title`` and the
+default disambiguators are ``year trackdisambig``.
 
 Syntax Details
 --------------