Documentation suggestion: edit and modify, relevance of -a option for changes to fields in path

[Vrihub]

Since I use $year in my paths: rules in config, I was wondering why my files paths did not get updated after making changes to the year field. Bug? Well, no, I finally realised that my queries lacked the -a option, so I was editing the year field of individual tracks, while the year field that is used by the paths: rules is actually the year field of the album object. This is a subtle difference that can be misunderstood by the novice user.

So, I suggest the following addition to the documentation of the modify command and of the edit plugin: the paragraph that documents the -a option could be extended with something like the following:

Using the -a option allows you to make changes to album fields, instead of track fields. This is relevant if you are using the year field in your paths format configuration [link to config.html#path-format-configuration]: if you need to make changes to that field, make sure to use the -a option in your query; in this way, you will be changing the album's year field (not the tracks one), and the new value will be used to also update the path in the library and on the filesystem.

[sampsyo]

Yeah, this is pretty confusing—in fact, it's a documented problem in #561. I think the "right" solution for this is to make modify just do the right thing, but a documentation change wouldn't be a bad thing either.

That paragraph looks like a good start. One suggestion: this isn't just about year; it's about any album-level field such as "album" or "albumartist" or "original_month" or whatever. With that clarification, would you mind opening a PR?

[abigaildelarosa]

Hello,

I was reading this issue and would like to suggest to change the paragraph for the next one:

The -a switch operates on albums instead of individual tracks. This is relevant if you are working with any kind of album field in your paths format (configuration)[http://beets.readthedocs.io/en/v1.4.3/reference/config.html]: in case that you need to change any album field such as year, album, albumartist etc, do not forget to add the command -a in the query. Otherwise you will be changing the track fields. Keep in mind that the new value will be used to update the path in the library and on the filesystem. 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 overridden with -w (write tags, the default) and -W (don't write tags).

What do you think about it @sampsyo ?

[sampsyo]

This additional text sounds very reasonable! Just to check, this would go on the cli.rst page under the section for modify, right?

If so, would you mind opening a pull request? We can go from there. Thanks for taking a crack at it! ✨