Update changelog and documentation

docs/changelog.rst

@@ -23,6 +23,9 @@ New features:
 * Beets now uses ``platformdirs`` to determine the default music directory.
   This location varies between systems -- for example, users can configure it
   on Unix systems via ``user-dirs.dirs(5)``.
+* :doc:`/plugins/substitute`: Allow the replacement string to use capture groups
+  from the match. It is thus possible to create more general rules, applying to
+  many different artists at once.
 
 Bug fixes:
 

docs/plugins/substitute.rst

@@ -11,13 +11,28 @@ the ``rewrite`` plugin modifies the metadata, this plugin does not.
 
 Enable the ``substitute`` plugin (see :ref:`using-plugins`), then make a ``substitute:`` section in your config file to contain your rules.
 Each rule consists of a case-insensitive regular expression pattern, and a
-replacement value. For example, you might use:
+replacement string. For example, you might use:
 
     substitute:
         .*jimi hendrix.*: Jimi Hendrix
 
+The replacement can be an expression utilising the matched regex, allowing us
+to create more general rules. Say for example, we want to sort all albums by
+multiple artists into the directory of the first artist. We can thus capture
+everything before the first ``,``, `` &`` or `` and``, and use this capture
+group in the output, discarding the rest of the string.
+
+    substitute:
+        ^(.*?)(,| &| and).*: \1
+
+This would handle all the below cases in a single rule:
+
+    Bob Dylan and The Band -> Bob Dylan
+    Neil Young & Crazy Horse -> Neil Young
+    James Yorkston, Nina Persson & The Second Hand Orchestra -> James Yorkston
+
 
 To apply the substitution, you have to call the function ``%substitute{}`` in the paths section. For example:
-    
+
     paths:
         default: %substitute{$albumartist}/$year - $album%aunique{}/$track - $title