From e39dcfc002557b87cc0e54a56b3022e20ded8828 Mon Sep 17 00:00:00 2001 From: Dominik Schrempf Date: Fri, 3 Dec 2021 22:36:48 +0100 Subject: [PATCH] clarify `-a` option for `beet modify` See https://github.com/beetbox/beets/discussions/4172. I think the confusion arises because the documentation refers to the query. That is, when `-a` is given, albums are queried, not tracks. This is especially clear when using `beet list`, because then it truly lists "albums instead of items". However, for other commands, the distinction between what is queried and what is acted on should be made more clear. This PR fixes the section for `modify`, but there are more questions: - `remove` command: The documentation states that it acts on albums instead of individual tracks. I guess we should also amend that? I think the complete album including the tracks is deleted, or is that not true? - `move` command: I think the same is true for this command. If `-a` is given, the queried albums including all tracks are moved. - `update` command: The `-a` flag is not explained here. --- docs/reference/cli.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/reference/cli.rst b/docs/reference/cli.rst index 9b0e6f482..214956873 100644 --- a/docs/reference/cli.rst +++ b/docs/reference/cli.rst @@ -263,11 +263,11 @@ artist="Tom Tom Club"`` will change the artist for the track "Genius of Love." To remove fields (which is only possible for flexible attributes), follow a field name with an exclamation point: ``field!``. -The ``-a`` switch operates on albums instead of 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 +The ``-a`` switch also operates 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. Items will automatically be moved around when necessary if they're in your