Add --remove option to duplicates plugin

[JOJ0]

Description

The duplicates plugin currently only supports deleting files entirely, sometimes it's desired to only fix the library and keep files in place. This PR adds this possibility.

• Documentation.
• Changelog. (will add after review)
• Tests.

[github-actions]

Thank you for the PR! The changelog has not been updated, so here is a friendly reminder to check if you need to add an entry.

[github-actions]

Thank you for the PR! The changelog has not been updated, so here is a friendly reminder to check if you need to add an entry.

[Copilot]

Pull Request Overview

This PR introduces a new --remove option to the duplicates plugin so users can unlink items from the library without deleting their files.

• Added configuration and parsing for the --remove flag
• Updated the item-processing logic to handle remove vs delete
• Extended documentation to describe the new option

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
docs/plugins/duplicates.rst	Documented the --remove option and its default configuration
beetsplug/duplicates.py	Added remove to config defaults, CLI parser, and processing

Comments suppressed due to low confidence (3)

beetsplug/duplicates.py:140

• [nitpick] Clarify the help text to indicate that this option leaves files on disk (e.g., help="remove items from library, but not from disk") so users understand the difference from --delete.

            help="remove items from library",

beetsplug/duplicates.py:56

• Add unit tests for the --remove option to verify that items are removed from the library without deleting their files.

                "remove": False,

docs/plugins/duplicates.rst:99

• [nitpick] Include an example demonstrating the new --remove flag (for example, beet duplicates -x) in the Examples section to illustrate its usage.

Examples

[JOJ0]

I added a changelog entry and enabled auto-merge. If there's nothing else missing or worth noticing could you give the approval @wisp3rwind ? Thanks a lot!

[JOJ0]

I disabled auto-merge. When I get an approval from anyone @wisp3rwind @snejus I will press the merge button myself. Please approve it's a tiny change. Thanks!

[wisp3rwind]

LGTM, thanks 👍
(Small nitpick: The only other command with a --remove option is mbupdate apparently, which uses -r for the short form. Maybe, duplicates should do so as well instead of -x?)

(Note that I'm not really familiar with the duplicates plugin.)

It looks a bit like the plugin still isn't properly handling conflicting action options (what happens if --delete and --tag are given? Calling item.store() after item.remove() looks a little concerning). Probably, (some) actions should be made exclusive (at least upon executing them, maybe also warning the user about it).

Anyway, that's not a regression of this PR, but an issue that existed before.

[JOJ0]

LGTM, thanks 👍 (Small nitpick: The only other command with a --remove option is mbupdate apparently, which uses -r for the short form. Maybe, duplicates should do so as well instead of -x?)

Thanks for checking options. I did a grep in the codebase now and I think you mean the mbcollection plugin (mbupdate is the command, oh I see, never used it ;-)).

I think I'm too invested in UNIX programs and -r makes me think of --recursive, thus my choice. Anyway I'll change it to -r for consistency.

BTW I tried the mbcollection plugin and I get an API error even though I think I configured my musicibrainz section correctly in my beets conf. Not sure if this plugin is functioning anymore but only invested 5 minutes for it. Does it work for you maybe?

(Note that I'm not really familiar with the duplicates plugin.)

Same here.

It looks a bit like the plugin still isn't properly handling conflicting action options (what happens if --delete and --tag are given? Calling item.store() after item.remove() looks a little concerning). Probably, (some) actions should be made exclusive (at least upon executing them, maybe also warning the user about it).

Exactly, I briefly noted that here: #5832 (comment) but still I am unsure if some of them make sense together. Some definitely do not!

Anyway, that's not a regression of this PR, but an issue that existed before.

I'll merge it and make your post a new feature/refactor request.

[wisp3rwind]

Thanks for checking options. I did a grep in the codebase now and I think you mean the mbcollection plugin (mbupdate is the command, oh I see, never used it ;-)).

I think I'm too invested in UNIX programs and -r makes me think of --recursive, thus my choice. Anyway I'll change it to -r for consistency.

Yeah, it's probably always somewhat ambiguous. I'm not sure how much mbcollection is used, so I guess we could also consider changing which short form beets uses for --remove. It'd be nice to be consistent, however. Note that chown/chmod have -R though, and grep has both -r and -R, so there's no really universal standard.

BTW I tried the mbcollection plugin and I get an API error even though I think I configured my musicibrainz section correctly in my beets conf. Not sure if this plugin is functioning anymore but only invested 5 minutes for it. Does it work for you maybe?

No, I've never used it, only grepped for --remove.

Exactly, I briefly noted that here: #5832 (comment) but still I am unsure if some of them make sense together. Some definitely do not!

Anyway, that's not a regression of this PR, but an issue that existed before.

I'll merge it and make your post a new feature/refactor request.

👍