From 018910dba237270438ec096fb6ad24d7ddb87642 Mon Sep 17 00:00:00 2001 From: J0J0 Todos Date: Thu, 3 Aug 2023 09:41:12 +0200 Subject: [PATCH] Add docs for `mod -a --noinherit` option and further clarify `mod -a` docs: Even though e39dcfc002557b87cc0e54a56b3022e20ded8828 and the linked discussion already does a very good job on clarifying what is actually happening when `mod -a` is issued, this commit adds further details about the difference between the album query and what is actually modified. --- docs/reference/cli.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/reference/cli.rst b/docs/reference/cli.rst index da119d0f81..c72a76eab2 100644 --- a/docs/reference/cli.rst +++ b/docs/reference/cli.rst @@ -257,7 +257,7 @@ modify `````` :: - beet modify [-MWay] [-f FORMAT] QUERY [FIELD=VALUE...] [FIELD!...] + beet modify [-IMWay] [-f FORMAT] QUERY [FIELD=VALUE...] [FIELD!...] Change the metadata for items or albums in the database. @@ -274,13 +274,17 @@ name into the artist field for all your tracks, and ``beet modify title='$track $title'`` will add track numbers to their title metadata. -The ``-a`` switch also operates on albums in addition to the individual tracks. +The ``-a`` option changes to querying album fields instead of track fields and +also enables to operate on albums in addition to the individual tracks. Without this flag, the command will only change *track-level* data, even if all the tracks belong to the same album. If you want to change an *album-level* field, such as ``year`` or ``albumartist``, you'll want to use the ``-a`` flag to avoid a confusing situation where the data for individual tracks conflicts with the data for the whole album. +Modifications issued using ``-a`` by default cascade to individual tracks. To +prevent this behaviour, ``-I/--noinherit`` can be used. + Items will automatically be moved around when necessary if they're in your library directory, but you can disable that with ``-M``. Tags will be written to the files according to the settings you have for imports, but these can be