Edit Plugin
===========

The ``edit`` plugin lets you modify music metadata using your favorite text
editor.

Enable the ``edit`` plugin in your configuration (see :ref:`using-plugins`) and
then type:

::

    beet edit QUERY

Your text editor (i.e., the command in your ``$VISUAL`` or ``$EDITOR``
environment variable) will open with a list of tracks to edit. Make your changes
and exit your text editor to apply them to your music.

Command-Line Options
--------------------

The ``edit`` command has these command-line options:

- ``-a`` or ``--album``: Edit albums instead of individual items.
- ``-f FIELD`` or ``--field FIELD``: Specify an additional field to edit (in
  addition to the defaults set in the configuration).
- ``--all``: Edit *all* available fields.

Interactive Usage
-----------------

The ``edit`` plugin can also be invoked during an import session. If enabled, it
adds two new options to the user prompt:

::

    [A]pply, More candidates, Skip, Use as-is, as Tracks, Group albums, Enter search, enter Id, aBort, eDit, edit Candidates?

- ``eDit``: use this option for using the original items' metadata as the
  starting point for your edits.
- ``edit Candidates``: use this option for using a candidate's metadata as the
  starting point for your edits.

When editing an album during import (i.e., after you have chosen ``eDit`` or
``edit Candidates`` for an album import), the fields listed in ``albumfields``
are shown as a YAML header section before the per-track documents. This allows
you to edit album-level fields (such as ``album``, ``albumartist``, or any
configured ``albumfields`` entry) for all tracks at once. Fields that appear in
both ``itemfields`` and ``albumfields`` are shown only in the header section,
not per-track.

Also, please be aware that the ``edit Candidates`` choice can only be used with
the matches found during the initial search (and currently not supporting the
candidates found via the ``Enter search`` or ``enter Id`` choices). You might
find the ``--search-id SEARCH_ID`` :ref:`import-cmd` option useful for those
cases where you already have a specific candidate ID that you want to edit.

Configuration
-------------

To configure the plugin, make an ``edit:`` section in your configuration file.
The available options are:

- **itemfields**: A space-separated list of item fields to include in the editor
  by default. Default: ``track title artist album``
- **albumfields**: The same when editing albums (with the ``-a`` option).
  Default: ``album albumartist``. These fields are also shown as a YAML header
  during interactive import when editing an album import.