Skip to content

Commit

Permalink
clarify -a option for beet modify
Browse files Browse the repository at this point in the history
See beetbox#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.
  • Loading branch information
dschrempf committed Dec 3, 2021
1 parent f315a13 commit e39dcfc
Showing 1 changed file with 5 additions and 5 deletions.
10 changes: 5 additions & 5 deletions docs/reference/cli.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit e39dcfc

Please sign in to comment.